stafconnectionprovider.h

Software Testing Automation Framework (STAF)的开发代码

/*****************************************************************************/
/* Software Testing Automation Framework (STAF)                              */
/* (C) Copyright IBM Corp. 2001, 2004                                        */
/*                                                                           */
/* This software is licensed under the Common Public License (CPL) V1.0.     */
/*****************************************************************************/

#ifndef STAF_ConnectionProvider
#define STAF_ConnectionProvider

#include "STAF.h"
#include "STAFString.h"
#include "STAFDynamicLibrary.h"

#ifdef __cplusplus
extern "C" {
#endif

// Each Connection Provider must define a structure with a unique name
// (e.g. STAFTCPConnectionImpl, STAFLocalConnectionImpl) that extends this
// base structure
struct STAFConnectionImpl
{
};

// Each Connection Provider must define a structure with a unique name
// (e.g. STAFTCPConnectionProviderImpl, STAFLocalConnectionProviderImpl)
// that extends this base structure
struct STAFConnectionProviderImpl
{
};

typedef struct STAFConnectionImpl *STAFConnection_t;
typedef struct STAFConnectionProviderImpl *STAFConnectionProvider_t;
typedef struct STAFConnectionProviderFunctionTable
               STAFConnectionProviderFunctionTable;

typedef enum
{
    kSTAFConnectionProviderDuplex   = 0,
    kSTAFConnectionProviderInbound  = 1,
    kSTAFConnectionProviderOutbound = 2
} STAFConnectionProviderMode_t;

typedef enum
{
    kSTAFConnectionProviderStopped    = 0,
    kSTAFConnectionProviderStarting   = 1,
    kSTAFConnectionProviderActive     = 2,
    kSTAFConnectionProviderStopping   = 3
} STAFConnectionProviderState_t;


typedef enum
{
    // The "port" property is a string which can be appended to an endpoint
    // string to enable a protocol configured on one "port" to connect to a
    // compatible protocol connection provider configured for a different
    // "port".  Note, while this is used to represent the actual port on a
    // remote endpoint when dealing with a TCP/IP connection provider, this
    // "port" may represent anything relevant to the connection provider.  This
    // property is meant to be opaque.  The only valid operation on this
    // property is an equality comparision with the "port" of a compatible
    // connection provider.

    kSTAFConnectionProviderPortProperty = 0,

    // The "isSecure" property indicates whether this connection provider
    // implements a secure protocol.  This property will be set to either
    // "0" if the protocol is not secure, or "1" if the protocol is secure.
    // Any value other than "0" or "1" should be treated as though it were
    // unsecure.

    kSTAFConnectionProviderIsSecureProperty = 1
} STAFConnectionProviderProperty_t;

/******************************************************************************/
/* STAFConnectionProviderNewConnection - This is called for every new         */
/*                                       connection accepted by the provider  */
/*                                                                            */
/* Accepts: (In)  Connection Provider                                         */
/*          (In)  Connection                                                  */
/*          (In)  Pointer to connection provider function table               */
/*          (In)  Pointer to data set at construction time                    */
/*                                                                            */
/* Returns: kSTAFOk                                                           */
/*                                                                            */
/* Notes  : Currently, the return code of this function is not used, but, to  */
/*          be safe it should always return kSTAFOk                           */
/******************************************************************************/
typedef STAFRC_t (* STAFConnectionProviderNewConnectionFunc_t)(
    STAFConnectionProvider_t provider,
    STAFConnection_t connection,
    const STAFConnectionProviderFunctionTable *funcTable,
    void *data);


typedef struct STAFConnectionProviderConstructInfoLevel1
{
    STAFConnectionProviderMode_t mode;

    unsigned int numOptions;
    STAFStringConst_t *optionNames;
    STAFStringConst_t *optionValues;
} STAFConnectionProviderConstructInfoLevel1;

typedef struct STAFConnectionProviderStartInfoLevel1
{
    STAFConnectionProviderNewConnectionFunc_t newConnectionFunc;
    void *data;
} STAFConnectionProviderConnectStartLevel1;

typedef struct STAFConnectionProviderConnectInfoLevel1
{
    STAFStringConst_t endpoint;
} STAFConnectionProviderConnectInfoLevel1;


/******************************************************************************/
/* Note: In all the functions below, if a non-zero pointer to an error buffer */
/*       is returned, it is the responsibility of the caller to call          */
/*       STAFStringDestruct on the error buffer.                              */
/******************************************************************************/

/******************************************************************************/
/* STAFConnectionProviderConstruct - Creates a connection provider            */
/*                                                                            */
/* Accepts: (Out) Pointer to connection provider                              */
/*          (In)  Pointer to constructor info                                 */
/*          (In)  Constructor info level                                      */
/*          (Out) Pointer to error buffer                                     */
/*                                                                            */
/* Returns: kSTAFOk, on success                                               */
/*          other on error                                                    */
/******************************************************************************/
STAFRC_t STAFConnectionProviderConstruct(STAFConnectionProvider_t *provider,
                                         void *constructInfo,
                                         unsigned int constructInfoLevel,
                                         STAFString_t *errorBuffer);


/******************************************************************************/
/* STAFConnectionProviderStart - Starts accepting connections                 */
/*                                                                            */
/* Accepts: (In)  Connection provider                                         */
/*          (In)  Pointer to start info                                       */
/*          (In)  Start info level                                            */
/*          (Out) Pointer to error buffer                                     */
/*                                                                            */
/* Returns: kSTAFOk, on success                                               */
/*          kSTAFInvalidOperation, if the provider is outbound only           */
/*          other on error                                                    */
/******************************************************************************/
STAFRC_t STAFConnectionProviderStart(STAFConnectionProvider_t provider,
                                     void *startInfo,
                                     unsigned int startInfoLevel,
                                     STAFString_t *errorBuffer);


/******************************************************************************/
/* STAFConnectionProviderStop - Stop accepting connections                    */
/*                                                                            */
/* Accepts: (In)  Connection provider                                         */
/*          (In)  Pointer to stop info                                        */
/*          (In)  Stop info level                                             */
/*          (Out) Pointer to error buffer                                     */
/*                                                                            */
/* Returns: kSTAFOk, on success                                               */
/*          other on error                                                    */
/******************************************************************************/
STAFRC_t STAFConnectionProviderStop(STAFConnectionProvider_t provider,
                                    void *stopInfo,
                                    unsigned int stopInfoLevel,
                                    STAFString_t *errorBuffer);


/******************************************************************************/
/* STAFConnectionProviderDestruct - Destroys a connection provider            */
/*                                                                            */
/* Accepts: (I/O) Pointer to connection provider                              */
/*          (In)  Pointer to destruct info                                    */
/*          (In)  Destruct info level                                         */
/*          (Out) Pointer to error buffer                                     */
/*                                                                            */
/* Returns: kSTAFOk, on success                                               */
/*          other on error                                                    */
/******************************************************************************/
STAFRC_t STAFConnectionProviderDestruct(STAFConnectionProvider_t *provider,
                                        void *destructInfo,
                                        unsigned int destructInfoLevel,
                                        STAFString_t *errorBuffer);


/******************************************************************************/
/* STAFConnectionProviderConnect - Connect to a "remote" endpoint             */
/*                                                                            */
/* Accepts: (In)  Connection Provider                                         */
/*          (Out) Pointer to connection                                       */
/*          (In)  Pointer to connect info                                     */
/*          (In)  Connect info level                                          */
/*          (Out) Pointer to error buffer                                     */
/*                                                                            */
/* Returns: kSTAFOk, on success                                               */
/*          kSTAFInvalidOperation, if the provider is inbound only            */
/*          other on error                                                    */
/******************************************************************************/
STAFRC_t STAFConnectionProviderConnect(STAFConnectionProvider_t provider,
                                       STAFConnection_t *connection,
                                       void *connectInfo,
                                       unsigned int connectInfoLevel,
                                       STAFString_t *errorBuffer);


/******************************************************************************/
/* STAFConnectionGetMyNetworkIDs - Get the logical and physical network       */
/*                                 identifiers for this connection provider   */
/*                                                                            */
/* Accepts: (In)  Connection                                                  */
/*          (Out) Pointer to logical network identifier                       */