smsapi.h

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

//                                  OTT_MORE_DATA: passed buffer not
//                                      big enough. *pCount says how
//                                      many containers registered.
//
// ==========================================================================
//
//  SmsEnumFolders
//
//  This API returns a list of all folders currently registered
//  in the folder registry. This list is actually an array of
//  FOLDER_INFO structs.
//
//  The memory for this array must be allocated by the caller.
//  To determine the size of the array call this API with NULL as
//  the first parameter. This will result in the number of filters
//  being returned in pCount.
//
//
//  Parameters:
//      FOLDER_INFO **pData         Pointer to an array of FOLDER_INFO structures.
//      DWORD *pCount               Pointer to count of folders.
//
//  Returns:
//      SMS_STATUS                  OTT_OK: success.
//                                  OTT_MORE_DATA: passed buffer not
//                                      big enough. *pCount says how
//                                      many containers registered.
//
// ==========================================================================
//
//  SmsDescribeFolder
//
//  This API retrieves information about a container/folder and returns
//  it in the FOLDER_INFO parameter (see description of FOLDER_INFO).
//  Because containers and folders share the same id space for their
//  tags, it is necessary for the caller to specify which one they are
//  interested in.
//  Note that the Enum... APIs return a set of objects, this API returns
//  only a single one.
//
//
//
//  Parameters:
//      BASETYPE tObjectity         T_CONTAINER or T_FOLDER
//                                  (do we want a container or folder).
//      DWORD dwTag                 Container/folder type.
//      FOLDER_INFO **ppFInfo       Store the retrieved FOLDER_INFO here.
//
//  Returns:
//      SMS_STATUS                  OTT_OK: success.
//                                  OTT_INVALID_CONTAINER_ID:
//                                  OTT_INVALID_FOLDER_ID:
//                                      The container/folder cannot be
//                                      located in the registry.
//
//===========================================================================
//  3.  Container APIs.
//===========================================================================
//
//  SmsOpenContainer
//
//  Opens a container of the specified type (cType). The container is opened
//  but is currently empty. The only operations that can be performed on it
//  in this state is SetFilter, Populate, and CloseContainer.
//  It is permissible to have multiple containers of the same type opened
//  simultaneously.
//  Only when a container has been populated does it have information that
//  can resonably be examined.
//  The container type is one of the C_xxx manifests in the list above.
//
//  Parameters:
//      DWORD cType                     Type of the container to open.
//                                      This should be one of thr C_xxx
//                                      manifests above.
//      HANDLE hConnect                 Handle to a connection that has been
//                                      established via SmsDataSourceConnect.
//      HANDLE *phContainer             Handle to the container, filled in by
//                                      the API.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsSetFilter
//
//  This API submitts a filter to the container. The filter consists
//  of tokens (possibly grouped) which express conditions for folder
//  inclusion within a container.
//  Note: when applying multiple filters an implicit AND is performed between
//  filters.
//
//  Parameters:
//      HANDLE hContainer               Identifies the container.
//      HANDLE hFilter                  Handle to the filter to assign to
//                                      the container.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsPopulate
//
//  This causes the container to be populated with folders according to the
//  filters applied to the container.
//  It should be noted that not all filters that are applied to a container
//  will be activated at this stage. For instance, applying an attribute
//  filter to a site container has no effect at this stage. However, the
//  filter is held internally within the system and will be applied to the
//  appropriate folder. For an attribute filter, its activation in a site
//  container would come at the level of a child domain folder. This
//  technique is known as percolating filters.
//  Containers are the only level at which filters can be applied at the
//  API level.
//  The dwOpts parameter allows the caller to specify whether the population
//  (and the folder retrieval) should be asynchronous or synchronous.
//  Synchronous is the default. These options are described earlier (see
//  "Populate options").
//  This parameter also specifies how the event handle should be set. The
//  event handle can be set by the API whenever a folder has been retrieved,
//  when all folders have been retrieved, or it can not be used at all (the
//  default).
//
//  A third parameter is an event handle. According
//
//  Parameters:
//      HANDLE hContainer               Identifies the container.
//      DWORD dwOptions                 Synchronous/asynch, event handle usage.
//      NOTIFY *pNotify                 Contains information about asynchronous
//                                      notification. NULL if synchronous.
//                                      parameter.
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsGetNextFolder
//
//  This API retrieves the next folder in a parent container or folder.
//
//  Parameters:
//      HANDLE hParent                  Identifies the parent (container or
//                                      folder).
//      DWORD fType                     Which type of sub-folder we want to
//                                      retrieve.
//      HANDLE *phFolder                Receives a handle to the next
//                                      folder in the parent.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsCloseContainer
//
//  Closes a currently open container, and frees resources held be the
//  container.
//  It is possible to open a container's child folders and then close the
//  container. This has no adverse effects on either the folders or on any
//  filters that have been applied to the container.
//
//  Parameters:
//      HANDLE hContainer               Identifies the container.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//  4.  Folder APIs.
//===========================================================================
//
//  SmsCreateFolder
//
//  This API attempts to create a folder (initally empty) of the specified
//  type. Folder creation is done in the context of a parent (folder or
//  container). Not all containers/folder support folder creation.
//  Once created, a folder must have its scalars set by the application.
//  Failure to do so will result in the system not accepting the newly
//  created folder. See DescribeFolder for information on retrieving details
//  about a folder's scalars.
//
//  Parameters:
//      HANDLE hParent                  Identifies the parent (can be either
//                                      container or folder).
//      DWORD fType                     The type of folder to create. See
//                                      the list of folders above).
//      char *pszFolderID               A name to give the folder. Not all
//                                      creatable folders can be named by the
//                                      user. In many cases SMS itself will
//                                      assign the name.
//      HANDLE *phFolder                Receives a handle to the newly-created
//                                      folder (if successful).
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsGetFolderID
//
//  This API retrives the ID/name of the folder referenced by the folder handle.
//
//  Parameters:
//      HANDLE hFolder                  Which folder object we're talking about.
//      char *pszFolderID               Pointer to buffer to receive the
//                                      folder's ID. It is the caller's
//                                      responsibility to ensure that this
//                                      buffer is large enough. If in doubt
//                                      use of buffer of size SMS_DATA_BUFF_SIZE.
//                                      This is guaranteed to be sufficient.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsGetFolderType
//
//  This API retrieves the folder's type as both an integer value and as
//  a character string. For instance invoking this API on a domain folder
//  will result in a type string of "Domain folder" and an integer type of
//  F_DOMAIN being returned. The caller is responsible for ensuring that
//  the character buffer is of sufficient size.
//
//  Parameters:
//      HANDLE hFolder                  The folder to query.
//      DWORD *pfType                   Receive's the folder's type (integer).
//      char *pszfType                  Receives folder's type (as a string).
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsEnumFolderTypes
//
//  This API returns an array of DWORDs which indicate what folder types
//  CAN be contained within this folder. It is the caller's responsibility
//  to ensure that the DWORD array (*pfTypes) is of sufficient size.
//  Calling this API with pfTypes of NULL or with *pctFolderTypes of 0,
//  will result in the correct count being returned to the caller in
//  pctFolderTypes.
//  If the *pctFolderTypes is less than the number of folders, then up to
//  *pctFolderTypes are returned in the DWORD array, and a status of
//  SMS_MORE_DATA is returned.
//  If *pctFolderTypes is greater than the number of folders then the maximum
//  number of folder types will be stored in the array, and a value of
//  PARAMETER_ERROR returned. *pctFolderTypes will be updated to indicate
//  the number of folder types.
//
//  Note the difference between this API and GetFolderCount. This returns
//  a list of sub-folder types that can be contained in the folder,
//  GetFolderCount returns a count of how many sub-folders of a specified
//  type actually are contained in the folder.
//
//  Parameters:
//      HANDLE hFolder                  The folder to query.
//      DWORD *pfTypes                  Points to an array of DWORD.
//                                      Filled in with the types of sub-
//                                      folders that this folder can contain.
//      DWORD *pctFolderTypes           How many types of sub-folders this
//                                      folder can contain.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsGetFolderCount
//
//  This API returns (in the DWORD parameter) how many sub-folders of the
//  specified folder-type are contained in this folder.
//  Note that a DWORD of F_ANY means return the total count of sub-folders.
//
//  Parameters:
//      HANDLE hFolder                  The folder (or container) to query.
//      DWORD fType                     Which type of sub-folder we're
//                                      interested in. F_ANY means all types.
//      DWORD *pctFolders               Receives the count.
//
//  Returns:
//      SMS_STATUS                      Status. Either SMS_OK or one of the
//                                      error codes listed above.
//
//===========================================================================
//
//  SmsGetFolderByID
//
//  This API the retrieves from the folder a sub-folder of the specified
//  type and with a specified ID.
//  This method of folder retrieval is non-sequential. Once a sub-folder has
//  been retrieved it can be re-retrieved. It is always legal to open a
//  folder multiple times. Doing this will create multiple instances of a
//  folder. Thus, it is possible to retrieve a folder twice, close once
//  instance, and still have an instance of the folder available.
//  Note that a folder type of F_ANY is not accepted here, it will result