SmsGetNextScalar

The SmsGetNextScalar function retrieves the next scalar in the list of scalars within a folder or persistent filter and writes the scalar's information into a SCALAR structure.

SMS_STATUS SmsGetNextScalar(
  HANDLE hFolder,        // Handle to folder or persistent filter.
  SCALAR *pScalarStruct  // Pointer to SCALAR structure to receive 
                         // scalar data.
);
 

Parameters

hFolder

Specifies the handle to the folder or persistent filter from which you want to retrieve the next scalar.

Note that scalars for persistent filters can be retrieved in sequence only by using SmsGetNextScalar. SmsGetScalarByName cannot be used to retrieve scalars from a persistent filter.

pScalarStruct

Points to a SCALAR structure that will receive the information for the scalar to be retrieved. Your application is responsible for allocating the memory for this structure.

If the scalar is of type SCALAR_STRING or SCALAR_BINARY, your application must ensure that the buffer for the string or binary is large enough for the value of the scalar. Note that the pszValue member points to a string buffer and the pValue member points to a buffer for a binary.

To get the correct size for the buffers, call the SmsGetNextScalar function with the dwLen member of the pScalarStruct structure set to NULL. SmsGetNextScalar will assign the size of the string or binary value and return a status of SMS_MORE_DATA. After your application gets the size of the value, it should create a buffer large enough for the value and assign a pointer to that buffer to the pszValue member for SCALAR_STRING or pValue for SCALAR_BINARY. Then call the SmsGetNextScalar function again using a pScalarStruct structure with the correct size for dwLen and a pointer to a sufficiently sized buffer for the pszValue (SCALAR_STRING) or pValue (SCALAR_BINARY).

Caution Some string scalars may contain embedded control characters. For example, the STRING_1 through STRING_10 attributes for folders with the SMSEvent architecture contain embedded newline and other control characters. Your application is responsible for detecting and handling these control characters.

Return Values

The SmsGetNextScalar 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 parent handle is not a valid folder handle or filter handle.

SMS_FOLDER_ALREADY_DELETED

An action was attempted on a folder or persistent filter that has already been deleted.

SMS_MORE_DATA

The dwLen member of the pScalarStruct structure was set to NULL. SmsGetNextScalar sets the dwLen member to the size of the SCALAR_STRING or SCALAR_BINARY scalar value.

SMS_NO_MORE_DATA

No scalar was returned because the end of the scalar list was reached.

Remarks

The scalars for a folder can be retrieved in sequence or by the scalar name. The sequence of scalars within a folder or persistent filter is fixed for each type of folder or persistent filter. The sequence is determined by the SMS API. To retrieve scalars in sequence, use the SmsGetNextScalar function. To retrieve scalars by scalar name, use the SmsGetScalarByName function. SmsGetScalarByName retrieves the scalar with the specified scalar name from the folder and writes the scalar's information into a SCALAR structure.

Note that scalars for persistent filters can be retrieved in sequence only (by using SmsGetNextScalar).

The SmsRewind function enables your application to start from the beginning of the scalar list again.

See Also

SmsGetScalarByName, SmsRewind