smsapi.h

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

// **************************************************************************
//
//  File: SMSAPI.H
//
//  Copyright (c) 1994, 1995 Microsoft Corp.
//
//  This is the header file for the SMS API.
//
//  This file contains all data definitions, manifests, return codes and
//  API declarations that constitute the API set.
//
//
// **************************************************************************



// **************************************************************************
//
//  The SMS API set provides a set of interfaces to enable querying and,
//  in some cases creation and deletion, of data from an SMS database.
//
//  SMS contains numerous objects to which an ISV needs access. These objects
//  are (not in any particular order): packages, jobs, workstation command
//  lines, program items, sites, domains, machines, machine groups.
//
//  The SMS API is built using a technology known as the objectity technique.
//  This technique expresses all objects in terms of containers, folders,
//  and scalars. All SMS objects are thus expressed in these terms.
//  The advantage of this is that we have a standard interface to all
//  objects. That is, the API does not distinguish between, say, a job and
//  a machine.
//
//  The starting point is the container. There are certain types of container
//  defined (container types below). A container is opened and then
//  populated. The act of populating a container causes it to be filled with
//  folders of defned types. A folder can contain sub-folders and scalars.
//  Scalars are akin to leaf nodes in a hierarchy graph. The contain a
//  name, type, and value.
//
//  Much of the power to the objectity technique is provided by filters.
//  These are objects which specify selection criteria. Filters are applied
//  by the user at the container level, at which point the implementation of
//  the API will assume ownership of the filter. It is guaranteed that only
//  folders matching the filters will be included in the container hierarchy.
//
//  Every folder can contain a set of scalars. Not all folders do, for
//  example a machine folder does not. In some cases a folder contains a
//  defined set of scalars, in other cases the scalar set can only be
//  determined at run time. In cases where the scalar set is predetermined
//  it will be documented in supporting documentation.
//
//  The APIs behave in a uniform manner.
//  1. They all return a status code (SMS_STATUS).
//  2. Where a value needs to be returned, it is done via a reference
//     parameter.
//
//  An API is provided to determine the API version. Any problems involving
//  the SMS API should include the information provided by this API.
//
//  The first step in using the APIs to to establish a connection to a
//  datasource. Currently the only datasource supported in SQL, but the
//  API is designed in such a way that additional datasources can be
//  added. Two APIs are provided for dealing with datasources:
//  DataSourceConnect and DataSourceDisonnect. The connect API returns a
//  connection handle, this is used in subsequent calls to open containers.
//
//  Apart from these APIs, the rest of the API set is divided into four
//  groups:
//  1. Container APIs.
//  2. Folder APIs.
//  3. Scalar APIs.
//  4. Filter APIs.
//
//  1. Container APIs.
//  These allow a container to be opened, a filter to be applied to a
//  container, a container to be populated with folders, a folder to be
//  retrieved, and the container to be closed. An API also exists to
//  return the number of folders currently contained in a container.
//
//  2. Folder APIs.
//  These allow a for retrieval of various types of information about a
//  folder (its ID or name, its type, the number of sub-folders, the number
//  of scalars). Retrieval of sub-folders within a folder in both a
//  sequential fashion and by name. Retrieval of scalars (sequential and by
//  name. And closure of the folder.
//  An API exists to allow folder creation. However, this is implementation
//  dependant. That is, most folders do not permit creation, some (eg
//  ceratin types of jobs) do.
//
//  3. Scalar APIs.
//  There is a bit of overlap between this and the previous group. Although
//  scalar retrieval is included in the Folder API group, it can also be
//  considered a scalar API.
//  An API is provided to set/update the value of a scalar. This can
//  currently only be done in a folder that is being newly created.
//
//  4. Filter APIs.
//  APIs for opening and closing a filter, and adding tokens into a filter.
//  Filters are composed of one or more tokens of the same type. Some filters
//  permit grouping of tokens within the filter (ie machine filter). This
//  allows for complex boolean expressions.
//  Tokens differ between different filters, but have a common interface.
//  Tokens are contructed via the SmsAddToken API.
//
//  5. Filter container APIs
//  Certain filters can be persistent, that is they are saved in the database
//  and can be reloaded by separate processes. These filters can be created
//  either the APIs, or via the SMS Admin.
//   These APIs enable the retrieval of these filters from the datasource
//  and the commital of new filters into the datasource.
//  Currently machine filters are the only filters capable of exhibiting
//  persistence.
//
// **************************************************************************


#ifndef _SMSAPI_H_
#pragma option push -b -a8 -pc -A- /*P_O_Push*/
#define _SMSAPI_H_



// ====================================================================
//
//  Includes
//
// ====================================================================

#include <qrycodes.h>           // The query codes for Machine queries.

#include <smsinfo.h>            // Manifests related to scalar settings.

#include <objectty.h>           // Objectity engine.


#ifdef __cplusplus
extern "C" {
#endif



// ====================================================================
//
//  Datasource definition information.
//
// ====================================================================

//
// Supported datasources.
// (NOTE: only sql supported currently).
//
typedef enum { DB_SQL, DB_SQL_CONNECTED, DB_OTHER } DATASOURCE_TYPE;


//
// Prototype for a decryption function. This is the last parameter
// to the SQL_CONNECT_PARAMS structure.
// When a user calls the DataSourceConnect API he can pass in the
// user name and password in encrypted form. If the decryption function
// pointer is non-null the the API will attempt to call this function
// both for the user name and password.
// The decryption function is user-supplied, it is expected to return
// the decrypted data in the first parameter.
//

typedef void (*PDECRYPTFUNC)(char *pszBuffer, char *pszDecryptMe, char *pszKey);


//
//  The information block needed for the DataSourceConnect API.
//  1. SQL datasource.
//

typedef struct _SQL_CONNECT_PARAMS {
    DATASOURCE_TYPE ds;
    char *pszServer;                    // SQL Server name.
    char *pszUserName;                  // User name (possibly encrypted).
    char *pszPasswd;                    // Password (possibly encrypted).
    char *pszDbName;                    // Database name.
    char *pszKey;                       // Decryption key.
    PDECRYPTFUNC pFunc;                 // Pointer to a decryption function.
} SQL_CONNECT_PARAMS;


//
//  2. RESERVED DO NOT USE
//

typedef struct _SQL_CONNECT_CONNECTED_PARAMS {
    DATASOURCE_TYPE ds;
    HANDLE hDataSource;
    const char *pszAccessType;
} SQL_CONNECT_CONNECTED_PARAMS;



//
// This only has the type field. It is used for extracting the type
// in such a fashion that user code doesn't have to imply any
// particular data source. It has no use other than that.
//

typedef struct _GENERIC {
    DATASOURCE_TYPE ds;
} GENERIC;



// We can now define the DATASOURCE. It is a union of the structs above.
typedef union {
    GENERIC             type;
    SQL_CONNECT_PARAMS  sqlParams;
    SQL_CONNECT_CONNECTED_PARAMS sqlConnectedParams;
} DATASOURCE;





// ====================================================================
//
//  Return codes. See also objectty.h.
//
// ====================================================================
typedef DWORD SMS_STATUS;           // All APIs return an SMS_STATUS.

#define SMS_OK                          OTT_OK
#define SMS_MORE_DATA                   OTT_MORE_DATA
#define SMS_NO_MORE_DATA                OTT_NO_MORE_DATA
#define SMS_FOLDER_NO_UPDATE            OTT_FOLDER_NO_UPDATE

// Error codes when registering (and accessing) containers and filters
#define SMS_DUPLICATE_CONTAINER_ID      OTT_DUPLICATE_CONTAINER_ID
#define SMS_DUPLICATE_FOLDER_ID         OTT_DUPLICATE_FOLDER_ID
#define SMS_DUPLICATE_FILTER_ID         OTT_DUPLICATE_FILTER_ID

#define SMS_DUPLICATE_FILTER            OTT_DUPLICATE_FILTER

#define SMS_SCALAR_NO_UPDATE            OTT_SCALAR_NO_UPDATE
#define SMS_SCALAR_WRONG_TYPE           OTT_SCALAR_WRONG_TYPE
#define SMS_INVALID_CONTAINER_ID        OTT_INVALID_CONTAINER_ID
#define SMS_INVALID_FOLDER_ID           OTT_INVALID_FOLDER_ID
#define SMS_INVALID_FILTER_ID           OTT_INVALID_FILTER_ID

#define SMS_CONTAINER_NO_UPDATE         OTT_CONTAINER_NO_UPDATE

#define SMS_PARAMETER_ERROR             OTT_PARAMETER_ERROR
#define SMS_UNSUPPORTED                 OTT_UNSUPPORTED

// This is returned when a specific object
// (folder or scalar) is requested and not
// found. APIs returning this are GetFolderByID
// and GetScalarByName.
#define SMS_NOT_FOUND                   OTT_NOT_FOUND

#define SMS_PARENT_NOT_FOUND            OTT_PARENT_NOT_FOUND

#define SMS_CANT_DELETE                 OTT_CANT_DELETE

#define SMS_NEW_FOLDER                  OTT_NEW_FOLDER

// Error when attempting to multiply
// link a folder.
#define SMS_FOLDER_LINKED               OTT_FOLDER_LINKED

// Filter operations.
#define SMS_RANGE_ERROR                 OTT_RANGE_ERROR

// These are returned when a container
// operation is tried when it shouldn't be.
#define SMS_CONTAINER_NOT_POPULATED     OTT_CONTAINER_NOT_POPULATED
#define SMS_CONTAINER_POPULATED         OTT_CONTAINER_POPULATED


// Attempt to perform persistent operation
// on a non-persistent filter.
#define SMS_FILTER_NOT_PERSISTENT       OTT_FILTER_NOT_PERSISTENT

// Error return if the connection handle
// of a filter doesn't match that of a
// container to which the filter is being
// applied.
#define SMS_INVALID_CONNECTION_HANDLE   OTT_INVALID_CONNECTION_HANDLE
#define SMS_INVALID_FILTER_TYPE         OTT_INVALID_FILTER_TYPE

// Folder's can't be unlinked if there are multiple handles
// to the same object.
#define SMS_IN_USE_BY_OTHER             OTT_IN_USE_BY_OTHER

// User (ie non-engine) codes begin here.
#define SMS_ERROR                       (OTT_END + 1)
#define SMS_SQL_ERROR                   (OTT_END + 2)
#define SMS_INVALID_DATASOURCE          (OTT_END + 3)
#define SMS_INVALID_HANDLE              (OTT_END + 4)
#define SMS_INVALID_FOLDER_TYPE         (OTT_END + 6)

#define SMS_CONNECT_FAILED              (OTT_END + 7)
#define SMS_NO_CREATE                   (OTT_END + 8)
#define SMS_FOLDER_NOT_MODIFIED         (OTT_END + 9)
#define SMS_INCORRECT_FOLDER_TYPE       (OTT_END + 10)  // Unused.
#define SMS_INVALID_PARAMETER           (OTT_END + 11)
#define SMS_EMPTY                       (OTT_END + 12)

// Return when commiting a child folder
// and the parent folder must be committed.
#define SMS_PARENT_NEEDS_COMMIT         (OTT_END + 13)