SmsRewind

The SmsRewind function resets the internal folder and/or scalar index of an object (container, folder, filter container, or filter) so that the object's subfolders and scalars can be reiterated.

SMS_STATUS SmsRewind(
  HANDLE hObject,  // Handle to the container, folder, filter, or 
                   // filter container to rewind.
  DWORD dwOptions  // Items to rewind.
);
 

Parameters

hObject

Specifies the object to rewind. SmsRewind can be used to rewind the top-level folders within a container, the subfolders and/or scalars directly within a folder, the persistent filters within a filter container, or the scalars within a persistent filter.

dwOptions

Specifies the items to rewind within the object specified by hObject.

If hObject is a filter container, dwOptions specifies the type of persistent filter to rewind. See Filter Types. To rewind all filter types within the filter container, specify F_ANY as the filter type. Currently, MACHINE_FILTER is the only type of persistent filter supported by filter containers.

If hObject is a persistent filter, dwOptions must specify that the scalars be rewound with RW_ALL or RW_SCALAR.

If hObject is a container, dwOptions specifies whether to rewind a specific type of folder or all folders at the top level of the container. If RW_FOLDER or RW_ALL is specified, all subfolders that are directly beneath the object specified by hObject are rewound. A specific folder type can also be specified for dwOptions. See Folder Types. Note that only one specific folder type can be rewound by specifying a folder type (you cannot rewind multiple types with a single call to SmsRewind—unless you rewind all types).

If hObject is a folder, dwOptions specifies whether to rewind a specific type of folder, all folders, all scalars, or all folders and scalars directly beneath the folder.

RW_FOLDER

Rewind subfolders only.

RW_SCALAR

Rewind scalars only.

RW_ALL

Rewind both subfolders and scalars.

folder type

Rewind only a specific folder type within the folder. For the manifest constants for folders, see Folder Types.

Return Values

The SmsRewind function returns a status code SMS_STATUS. If successful, the function returns a status of SMS_OK. Otherwise, it returns one of the following manifest constants:

SMS_INVALID_HANDLE

The specified folder handle is not a valid folder handle.

SMS_INVALID_FILTER_ID

No filters of the specified filter type were found in the filter container.

Remarks

Because SmsGetNextFolder and SmsGetNextScalar read folders and scalars sequentially, your application must use SmsRewind to start at the beginning of the scalar or folder list again. SmsRewind enables your application to iterate the folders or scalars again from the beginning of the folder or scalar list. Note that SmsRewind also enables your application to rewind the persistent filters in a filter container or to rewind the scalars within a persistent filter.

When your application calls SmsGetNextFolder or SmsGetNextScalar and SMS_NO_MORE_DATA is returned, this means that your application has reached the end of the folder or scalar list and the folder needs to be rewound using SmsRewind.

The SmsRewind function is not recursive. If RW_ALL, RW_FOLDER, or RW_SCALAR is specified by dwOptions, only the count for the folders or scalars directly beneath the folder, container, filter container, or persistent filter specified by hObject are rewound.

If your application specifies a subfolder type with dwOptions, only folders of that specific folder type within that object are rewound. Note that the folder type must be directly beneath the specified object. By specifying the folder type, your application can rewind a single folder type (leaving the counts for the other folder types unaffected) rather than rewinding all folders. Specific folder types can only be rewound one type at a time.

See Also

SmsGetNextFilter, SmsGetNextFolder, SmsGetNextScalar