SmsEnumContainers

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

SMS_STATUS SmsEnumContainers(
  FOLDER_INFO **ppData,  // Pointer to an array of pointers to 
                         // FOLDER_INFO structures.
  DWORD *pCount          // Count of all container 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 container types supported by the SMS API. Your application must ensure that the array specified by ppData is large enough to contain the number of container types supported by the SMS API. See the following remarks.

pCount

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

Return Values

The SmsEnumContainers 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 container types in the DWORD specified by pCount. Or ppData or pCount were set to NULL and the count of container types was returned to pCount.

Remarks

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

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

If the value for pCount is less than the number of container types, the function assigns pointers for the number of container 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 container types, the function assigns pointers for all container 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 SmsEnumContainers function retrieves an array of information for all container types. The SmsDescribeFolder function retrieves the information for only the specified container type.

Example

// Get information about all container types.

DWORD ctContainers = 0;
static FOLDER_INFO **ppContainerList = NULL;

// Use SmsEnumContainers to get the number of container types.
SmsEnumContainers(NULL, &ctContainers);

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

// Use SmsEnumContainers to get the information 
// about the container types.
SmsEnumContainers(ppContainerList, &ctContainers);
 

See Also

FOLDER_INFO, SmsDescribeFolder, SmsEnumFolders