SmsEnumObjects

The SmsEnumObjects function enumerates objects.

SMS_STATUS SmsEnumObjects(
  HANDLE hConn,         // Handle to a connection that has been 
                        // established via SmsDataSourceConnect.
  char *pszObjectType,  // Pointer to the object type you want to 
                        // enumerate.
  SMSBUFF *pPredecessors,  // Pointer to an array of predecessor 
                           // objects required for locating the 
                           // requested object.
  DWORD ctPredecessors, // Size of the pPredecessors array.
  OJBDESCRIPTOR *pObjects,  // Pointer to an array containing the 
                            // details of the requested object type.
  DWORD *pCtObjects     // On entry, points to the size of the 
                        // pObjects array; on exit, points to the 
                        // actual number of requested objects known to 
                        // the system.
);
 

Parameters

hConn

Handle to a connection that has been established via the SmsDataSourceConnect function.

*pszObjectType

Points to the object type you want to enumerate.

*pPredecessors

For non-first-class objects, this parameter points to an array containing a list of the predecessor objects that must be given to the system in order to locate the requested object. For first-class objects, this parameter is not used and may be set to NULL.

ctPredecessors

Specifies the number of entries in the pPredecessors array.

*pObjects

Points to an array containing the details of the requested object type. Your application must ensure that the array specified by pObjects is large enough to contain the number of requested objects. See the following remarks.

*pCtObjects

On entry, this parameter points to a DWORD value that specifies the number of entries in the pObjects array. On exit, this parameter points to a DWORD value that contains the actual number of the requested objects known to the system.

Return Values

The SmsEnumObjects 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_MORE_DATA

The entry value of pCtObjects is less than the number of objects known to the system. The function returns this value in pCtObjects, but does not copy any information to the pObjects array.

SMS_PARAMETER_ERROR

The value of pszObjectType is NULL.

SMS_NOT_FOUND

Either the object type pointed to by pszObjectType or the predecessor objects pointed to by pPredecessors were not found.

SMS_ERROR

The internal object lists could not be found. This indicates a fundamental error related to the connection to the SMS database.

Remarks

The pPredecessor parameter is not used for first-class objects (that is, objects that are known directly by the API without any additional information). In this case, pPredecessor may be set to NULL.

To get the correct size for the pObjects array, call the SmsEnumObjects function with pObjects set to NULL or with pCtObjects set to zero. SmsEnumObjects will assign the count of the requested objects to pCtObjects and return a status of SMS_MORE_DATA. After getting the correct value for pCtObjects, call the SmsEnumObjects function again using the correct value for pCtObjects and a pObjects array with a size that matches the count specified by pCtObjects.

If the entry value of pCtObjects is less than the number of the requested objects known to the system, the function does not copy any information to the pObjects array and returns a status of SMS_MORE_DATA.

If the entry value of pCtObjects is greater than the number of the requested objects known to the system, the function writes all requested objects to the pObjects array and returns a status of SMS_OK.

See Also

SmsDataSourceConnect, SmsEnumObjectTypes