SmsEnumFolders

The SmsEnumFolders function retrieves a pointer to an array of pointers to FOLDER_INFO structures that contain information about the folder types supported by the SMS API.

SMS_STATUS SmsEnumFolders(
  FOLDER_INFO **ppData,  // Pointer to an array of pointers to 
                         // FOLDER_INFO structures.
  DWORD *pCount          // Count of all folder types supported by 
                         // the SMS API.
);
 

Parameters

ppData

Points to a pointer to an array of pointers to FOLDER_INFO structures that contain the information about the folder types supported by the SMS API. Your application must ensure that the array specified by ppData is large enough to contain the number of folder types supported by the SMS API. See the following remarks.

pCount

Points to the count of folder types supported by the SMS API.

Return Values

The SmsEnumFolders function returns a status code SMS_STATUS. If successful, the function returns a status of SMS_OK. Otherwise, it returns the following manifest constant:

SMS_MORE_DATA

The buffer specified by ppData is not big enough, and the function returns the count of folder types in the DWORD specified by pCount. Or ppData or pCount were set to NULL and the count of folder types was returned to the pCount.

Remarks

Your application must ensure that the array specified by ppData is large enough to contain the number of folder types supported by the SMS API.

To get the correct size for the ppData array, call the SmsEnumFolders function with ppData set to NULL or with pCount set to zero. SmsEnumFolders will assign the count of folder types to pCount and return a status of SMS_MORE_DATA. After getting the correct value for pCount, call the SmsEnumFolders function again using the correct value for pCount and a ppData array with a size that matches the count specified by pCount.

If the value for pCount is less than the number of folder types, the function assigns pointers for the number of folder types specified by pCount to the ppData array and returns a status of SMS_MORE_DATA.

If the value for pCount is greater than the number of folder types, the function assigns pointers for all folder types to the ppData array and returns a status of SMS_OK.

The FOLDER_INFO structures reside in the address space of the SMS API engine. This structure should not be modified or deallocated.

The FOLDER_INFO structure contains information that describes the properties of a type of container or folder. The container functions and folder functions are used to access specific containers and folders that represent objects in the SMS site database. In short, the FOLDER_INFO structure is used to get the general properties of a certain kind of container or folder, and the container and folder functions are used to access actual containers and folders.

Note that the SmsEnumFolders function retrieves an array of information for all folder types. The SmsDescribeFolder function retrieves the information for only the specified folder type.

Example

// Get information about all folder types.

DWORD ctFolders = 0;
static FOLDER_INFO **ppFolderList = NULL;

// Use SmsEnumFolders to get the number of folder types.
SmsEnumFolders(NULL, &ctFolders);

// Allocate memory for the array of pointers to the 
// FOLDER_INFO structures.
ppFolderList = new FOLDER_INFO *[ctFolders];

// Use SmsEnumFolders to get the information about the folder types.
SmsEnumFolders(ppFolderList, &ctFolders);
 

See Also

FOLDER_INFO, SmsDescribeFolder, SmsEnumContainers