SmsGetNextFolder

The SmsGetNextFolder function retrieves the handle to the next folder in the container or to the next subfolder within a folder.

SMS_STATUS SmsGetNextFolder(
  HANDLE hParent,  // Handle to the parent container or folder 
                   // containing the folder to get.
  DWORD fType,     // Type of folder.
  HANDLE *phFolder // Pointer to handle to receive the handle to the 
                   // next folder.
);
 

Parameters

hParent

Specifies the handle to the parent container or to the parent folder containing the folder to retrieve.

fType

Specifies the type of folder to retrieve. See Folder Types.

phFolder

Receives the handle to the next folder of the type specified by fType in the parent container or folder.

Return Values

The SmsGetNextFolder 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 container handle or folder handle is not valid.

SMS_NO_MORE_DATA

No folder was retrieved because the end of the folder list was reached.

SMS_INVALID_FOLDER_TYPE

The folder type specified was not one of the types that can be contained in the folder or container.

SMS_CONTAINER_NOT_POPULATED

The specified container is not populated.

SMS_NOT_READY

An asynchronous populate has completed and the SMS API engine has returned a "not ready" status while retrieving the next folder from the site database.

SMS_ERROR

An unexpected error occurred.

Remarks

After a container has been populated, the order of the folders within that particular container is fixed. The sequence of folders within a container or folder is determined by the order in which the SMS API engine retrieved those folders from the site database. Using the SmsGetNextFolder function, your application can access the folders in the container sequentially. SmsGetNextFolder returns the handle to the next folder in the list of folders within a container.

Before calling SmsGetNextFolder, your application must call SmsPopulate to populate the container. If the container is not populated, SmsGetNextFolder returns SMS_CONTAINER_NOT_POPULATED.

Because SmsGetNextFolder reads folders sequentially, your application must explicitly reset the folder list to start at the beginning of the list again. When SmsGetNextFolder has reached the end of the folder list, it returns SMS_NO_MORE_DATA.

To start at the beginning of the folder list again, use SmsRewind. SmsRewind enables your application to iterate the folders again from the beginning of the folder list.

Note that your application can use only SmsGetNextFolder to retrieve top-level folders in a container. Top-level folders in a container can only be retrieved by sequence. This means that SmsGetFolderByID cannot be used to retrieve a top-level folder in a container.

See Also

SmsPopulate, SmsRewind