smsapi.h

希望我上传的这些东西可以对搞编程的程序员有点小小的帮助！谢谢！

//  in a return code of SMS_INVALID_FOLDER_TYPE.
//  Note that a type of F_ANY is not allowed.
//
//
//  Parameters:
//      HANDLE hFolder                  The folder to query.
//      DWORD fType                     Which type of sub-folder we want to
//                                      retrieve (see GetFolderCount).
//      char *pszFolderID               The sub-folder's ID (name).
//      HANDLE *phSubFolder             Receives a handle to the sub-folder.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsRewind
//
//  This API resets the internal counts of either a container, a folder, or
//  a filter so that contained sub-folders and/or scalars can be re-
//  enumerated.
//  Because GetNextFolder and GetNextScalar are sequential, once thay have
//  been retrieved once they cannot be re-retrieved with these APIs.
//  The Rewind API enbles the retrieval to be restarted.
//  The options parameter allows the user to specify that either the folder
//  list or the scalar list or both be rewound.
//
//
//  Parameters:
//      HANDLE hObject                  The container, folder, or filter
//                                      to be rewound.
//      DWORD  dwOptions                Rewind options:-
//                                      RW_FOLDER: rewind folder lists.
//                                      RW_SCALAR: rewind scalar lists.
//                                      RW_ALL:    both.
//
//                                      If the object is a container or
//                                      folder, a particular type of sub-
//                                      folder list may be rewound by passing
//                                      the child folder type in the
//                                      dwOptions parameter.
//
//                                      If the object is a filter container,
//                                      then a particular type of filter list
//                                      may be rewound by passing the filter
//                                      type in the dwOptions parameter.
//
//                                      If the object is a filter then only
//                                      RW_SCALAR is valid.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//

//===========================================================================
//
//  SmsCloseFolder
//
//  This API closes the specified folder.
//  Closing a folder causes sub-folders to be closed and deallocated UNLESS
//  they have already been retrieved by a GetSubFolder/GetFolderByID call
//  in which case they remain open.
//  A folder's scalars are always closed and their memory deallocated.
//
//  Parameters:
//      HANDLE hFolder                  The folder to close.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsLinkFolder
//
//  This API inserts the specified folder into the in-memory list of folders
//  and causes it to be linked to its parent (must still be open).
//  The folder is not written back to the datasource until CommitFolder is
//  called.
//
//  Parameters:
//      HANDLE hFolder                  The folder to insert.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsUnlinkFolder
//
//  This API deletes the specified folder from the in-memory list of folders.
//  All memory associated with the folder is deallocated. However, the
//  folder is not deleted from the datasource until CommitFolder is called.
//
//  Parameters:
//      HANDLE hFolder                  The folder to delete.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsCommitFolder
//
//  This API causes any changes in the specified folder to be written back to
//  the datasource.
//  This should be called after LinkFolder and UnlinkFolder in order to make
//  the changes permanent.
//  Note that a Commit following an Unlink will render the specified folder
//  unavailable to all operations (other that SmsCloseFolder).
//
//  Parameters:
//      HANDLE hFolder                  The folder to update (insert or delete).
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsDupFolder
//
//  This API causes the folder (hFolder) to be copied (into hNewFolder)
//  in the context of the specified parent (hParent - container or folder).
//
//  Parameters:
//      HANDLE hParent                  The parent folder in whose context
//                                      the new folder will be inserted.
//      HANDLE hFolder                  The folder to be duplicated
//      HANDLE *phNewFolder             The handle to the new folder
//                                      is returned here.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//  5.  Scalar APIs.
//===========================================================================
//
//  SmsGetScalarCount
//
//  This API returns the count of scalars in this folder.
//
//  Parameters:
//      HANDLE hFolder                  The folder to query.
//      DWORD *pctScalars               Receives the count of scalars.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsGetNextScalar
//
//  This API retrieves the next scalar from the folder.
//  Scalars can either be retrieved in a sequential fashion (this API)
//  or by name (GetScalarByName). The RewindFolder API enables the sequential
//  enumeration of scalars to be restarted.
//
//  Parameters:
//      HANDLE hFolder                  The folder to query.
//      SCALAR *pScalar                 Pointer to a SCALAR that has been
//                                      allocated by the caller.
//                                      See notes on SCALAR for a full
//                                      description of this structure and
//                                      its use.
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsGetScalarByName
//
//  This API retrieves the scalar specified by its name.
//
//  Parameters:
//      HANDLE hFolder                  The folder to query.
//      const char *pszName             Name of the scalar.
//      SCALAR *pScalar                 Pointer to a SCALAR that has been
//                                      allocated by the caller.
//                                      See notes on SCALAR for a full
//                                      description of this structure and
//                                      its use.
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsSetScalar
//
//  This API is used to set the value of a scalar. It is used when creating a
//  folder. In the future it will also be used to modify the value of a
//  scalar in an existing folder.
//  The set of scalars supported by a folder is always known at the time a
//  folder is opened, this is true even when a folder is being created.
//  Scalars have a name, a type, and a value. This API allows the value to
//  be set. Only values of the correct type are allowed. Attempting to set,
//  for instance, an integer value in a string scalar will result in a
//  SMS_SCALAR_WRONG_TYPE error return.
//  The API set supports the notion of access rights on folders and scalars,
//  in order for this API to succeed the caller must have the correct
//  access to both. Failure results in an error return of SMS_SCALAR_NO_UPDATE
//  or SMS_FOLDER_NO_UPDATE.
//
//  Parameters:
//      HANDLE hFolder                  The folder containing the scalar.
//      SCALAR *pScalar                 Pointer to a SCALAR that has been
//                                      allocated and filled in by the caller.
//                                      See notes on SCALAR for a full
//                                      description of this structure and
//                                      its use.
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//  6.  Filter container APIs.
//===========================================================================
//
//  SmsOpenFilterContainer
//
//  The filter container is a storage mechanism for persistent filters,
//  currently only Machine Filters (SMS Queries) fall into this category.
//
//  Calling this API causes the filter container to be automatically populated
//  with all persistent filters in the system.
//
//  Parameters:
//      HANDLE hConnection              Which connection to use.
//      HANDLE *phFContainer            Receives the handle to the opened
//                                      filter container.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or an error code.
//                                      LIST POSSIBLE ERROR CODES HERE.
//
//===========================================================================
//
//  SmsCloseFilterContainer
//
//  Closes the filter container. All filters container herein that have
//  not been explicitly opened are closed and the memory associated with
//  them is freed.
//
//  Parameters:
//      HANDLE hFContainer              The handle to the filter container.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or an error code.
//                                      LIST POSSIBLE ERROR CODES HERE.
//
//===========================================================================
//
//  SmsGetNextFilter
//
//  This returns (in *phFilter) a handle to the next sequential filter of
//  the specified type from the filter container (specified by hFContainer).
//  A filter type of F_ANY is not acceptable.
//
//  Parameters:
//      HANDLE hFContainer              Handle to the filter container.
//      DWORD frType                    Filter type.
//      HANDLE *phFilter                Handle to the filter returned here.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or an error code.
//                                      LIST POSSIBLE ERROR CODES HERE.
//
//===========================================================================
//
//  SmsGetFilterByID
//
//  The API will return (in *phFilter) a handle to the filter of the specified
//  type which has the specified ID.
//  As above, the handle to the filter container is also passed into the API.
//  A filter type of F_ANY is not acceptable.
//
//  Parameters:
//      HANDLE hFContainer              Handle to the filter container.
//      DWORD frType                    Filter type.
//      const char *pszID               ID of the filter to retrieve.
//      HANDLE *phFilter                Handle to the filter returned here.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or an error code.
//                                      LIST POSSIBLE ERROR CODES HERE.
//
//===========================================================================
//
//  SmsGetFilterID
//
//  This returns, in pszID, the ID of the filter specified by the handle.
//
//  Parameters:
//      HANDLE hFilter
//      char *pszID
//
//  Returns: