SmsEnumFolderTypes

The SmsEnumFolderTypes function retrieves an array of DWORD values that indicate the types of subfolders supported by a folder or a container.

SMS_STATUS SmsEnumFolderTypes(
  HANDLE hFolder,  // Handle to a folder or container.
  DWORD *pfTypes,  // Points to an array of DWORD values to receive 
                   // the folder types.
  DWORD *pctFolderTypes
                   // Points to the count of the folder types.
);
 

Parameters

hFolder

Specifies the handle to the folder or container to query.

pfTypes

Points to an array of DWORD values. This array will receive the folder type values for the folder types supported by the specified folder or container.

Note that your application is responsible for allocating enough memory for the pfTypes array.

pctFolderTypes

Points to a DWORD value that specifies the number of folder types that the specified folder or container contains.

Return Values

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

SMS_MORE_DATA

The pfTypes parameter is NULL (returns count of folder types to pctFolderTypes), or the specified type count is less than the actual number of folder types (returns the number of items allocated for the pfTypes array). The operation completed successfully but more data is available.

SMS_PARAMETER_ERROR

The specified type count pctFolderTypes is greater than the actual number of folder types.

Remarks

The application must ensure that the array specified by pfTypes is large enough to contain the number of subfolder types for the folder specified by hFolder.

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

If the value for pctFolderTypes is less than the number of folders, the function writes the number of folder types specified by pctFolderTypes to the pfTypes array and returns a status of SMS_MORE_DATA.

If the value for pctFolderTypes is greater than the number of folder types, the function writes all folder types for the specified folder to the pfTypes array and returns a value of SMS_PARAMETER_ERROR.

Note the difference between the SmsEnumFolderTypes function and SmsGetFolderCount. SmsEnumFolderTypes returns a list of subfolder types that can be contained in the folder. SmsGetFolderCount returns a count of how many subfolders of a specified type actually are contained in a specific folder.

Example

This example calls the SmsEnumFolderTypes function twice to get an array that contains a list of the subfolder types supported by the folder. The first call gets the count of folder types for the folder. The second call uses the value received by pctFolderTypes to get the array.

// Call SmsEnumFolderTypes to get the count of folder types.

DWORD ctFolderTypes;
stat = SmsEnumFolderTypes(hFolder, // Handle to folder
                          NULL,    // Set array pointer to NULL to
                                   // return count to ctFolderTypes.
                          &ctFolderTypes // Receives folder type count.
                         );
// Call SmsEnumFolderTypes to retrieve the folder types in 
// the pfTypes array.
DWORD *pfTypes;
pfTypes = new DWORD[ctFolderTypes];
stat = SmsEnumFolderTypes(hFolder, // Handle to folder
                          pfTypes, // Pointer to array of
                                   // return count to ctFolderTypes.
                          &ctFolderTypes // Receives folder type count.
                         );