apiref.script

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

// Object functions

STAFRC_t STAFObjectGetType(STAFObject_t object, STAFObjectType_t *type);
STAFRC_t STAFObjectGetSize(STAFObject_t object, unsigned int *size);
STAFRC_t STAFObjectIsReference(STAFObject_t object, unsigned int *isRef);
STAFRC_t STAFObjectUnmarshallFromString(STAFObject_t *newContext,
                                        STAFStringConst_t string,
                                        STAFObject_t context,
                                        unsigned int flags);
STAFRC_t STAFObjectMarshallToString(STAFObject_t object, STAFObject_t context,
                                    STAFString_t *string, unsigned int flags);
STAFRC_t STAFObjectGetStringValue(STAFObject_t object, STAFString_t *string);

// Scalar functions

STAFRC_t STAFObjectScalarGetStringValue(STAFObject_t object,
                                        STAFStringConst_t *string);
STAFRC_t STAFObjectScalarGetUIntValue(STAFObject_t object,
                                      unsigned int *uInt,
                                      unsigned int defaultValue);

// List functions

STAFRC_t STAFObjectListAppend(STAFObject_t list, STAFObject_t object);

// Iterator functions

STAFRC_t STAFObjectConstructListIterator(STAFObjectIterator_t *iter,
                                         STAFObject_t list);
STAFRC_t STAFObjectIteratorHasNext(STAFObjectIterator_t iter,
                                   unsigned int *hasNext);
STAFRC_t STAFObjectIteratorGetNext(STAFObjectIterator_t iter,
                                   STAFObject_t *object);
STAFRC_t STAFObjectIteratorDestruct(STAFObjectIterator_t *iter);

// Map functions

STAFRC_t STAFObjectMapGet(STAFObject_t map, STAFStringConst_t key,
                          STAFObject_t *object);
STAFRC_t STAFObjectMapPut(STAFObject_t map, STAFStringConst_t key,
                          STAFObject_t object);
STAFRC_t STAFObjectMapHasKey(STAFObject_t map, STAFStringConst_t key,
                             unsigned int *hasKey);
STAFRC_t STAFObjectConstructMapKeyIterator(STAFObjectIterator_t *pIter,
                                           STAFObject_t map);
STAFRC_t STAFObjectConstructMapValueIterator(STAFObjectIterator_t *pIter,
                                             STAFObject_t map);

// Marshalling Context functions

STAFRC_t STAFObjectMarshallingContextSetMapClassDefinition(
    STAFObject_t context,
    STAFStringConst_t name,
    STAFObject_t mapClassDefinition);

STAFRC_t STAFObjectMarshallingContextGetMapClassDefinition(
    STAFObject_t context,
    STAFStringConst_t name,
    STAFObject_t *mapClassDefinition);

STAFRC_t STAFObjectMarshallingContextHasMapClassDefinition(
    STAFObject_t context,
    STAFStringConst_t name,
    unsigned int *pHasMapClassDefinition);

STAFRC_t STAFObjectMarshallingContextSetRootObject(STAFObject_t context,
                                                   STAFObject_t object);
STAFRC_t STAFObjectMarshallingContextGetRootObject(STAFObject_t context,
                                                   STAFObject_t *object);
STAFRC_t STAFObjectMarshallingContextAdoptRootObject(STAFObject_t context,
                                                     STAFObject_t *object);
STAFRC_t STAFObjectMarshallingContextGetPrimaryObject(STAFObject_t context,
                                                      STAFObject_t *object);
STAFRC_t STAFObjectConstructMapClassDefinitionIterator(
    STAFObjectIterator_t *pIter, STAFObject_t context);
:exmp.

.*
.*---------------------------------------------------------------------
.*
:ih1.C API
:i2.Private Data Manipulation APIs
:h3.Private Data Manipulation APIs
:p.STAF externalizes some APIs for handling private data in STAF command
request options.  Here are the definitions for these APIs.
:xmp.
// This method adds privacy delimiters to the data.
// For example, if data passed in is "secret", sets result
// to "!!@secret@!!".

STAFRC_t STAFAddPrivacyDelimiters(STAFStringConst_t data,
                                  STAFString_t *result);

// This method removes the specified number of levels of privacy
// delimiters from the data.  Set numLevels to 0 to remove all
// levels of privacy delimiters.
// For example, if data passed in is "!!@secret@!!", sets
// result to "secret".
                                  
STAFRC_t STAFRemovePrivacyDelimiters(STAFStringConst_t data,
                                     unsigned int numLevels,
                                     STAFString_t *result);

// This method masks any private data indicated by the privacy
// delimiters by replacing the private data with asterisks.
// For example, if data passed in is "!!@secret@!!", sets
// result to "************".
                                     
STAFRC_t STAFMaskPrivateData(STAFStringConst_t data, STAFString_t *result);

// This method escapes any privacy delimiters found in the data.
// For example, if data passed in is "!!@secret@!!", sets
// result to "^!!@secret^@!!".

STAFRC_t STAFEscapePrivacyDelimiters(STAFStringConst_t data,
                                     STAFString_t *result);
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.C API
:i2.Other Utility APIs
:h3.Other Utility APIs
:p.STAF externalizes some other general utility APIs.
Here are the definitions for these APIs.
:xmp.
/*********************************************************************/
/* STAFUtilFormatString - Generates a string based on a format       */
/*                        string, ala printf().  This is generally   */
/*                        used to format STAF request strings.       */
/*                                                                   */
/* Accepts: (In)  The format string                                  */
/*          (Out) A pointer to the output string                     */
/*          (In)  All data indicated in the format string            */
/*                                                                   */
/* Returns:  Standard return codes                                   */
/*                                                                   */
/* Notes  :  1) The caller is responsible for destructing the        */
/*              output string                                        */
/*********************************************************************/
/* Valid format string specifiers:                                   */
/*                                                                   */
/* %d - an unsigned integer                                          */
/* %s - a STAFString_t                                               */
/* %C - a STAFString_t which will be formatted in colon-length-colon */
/*      delimited format                                             */
/* %% - a percent sign                                               */
/*                                                                   */
/* Any other %<char> is simply ignored (and not copied)              */
/*********************************************************************/
unsigned int STAFUtilFormatString(STAFStringConst_t formatString,
                                  STAFString_t *outputString, ...);


/*********************************************************************/
/* STAFUtilFormatString2 - Generates a string based on a format      */
/*                         string, ala printf().  This is generally  */
/*                         used to format STAF request strings.      */
/*                                                                   */
/* Accepts: (In)  The format string                                  */
/*          (Out) A pointer to the output string                     */
/*          (In)  A variable argument list                           */
/*                                                                   */
/* Returns:  Standard return codes                                   */
/*                                                                   */
/* Notes  :  1) The caller is responsible for destructing the        */
/*              output string                                        */
/*           2) Valid format strings are the same as defined for     */
/*              STAFUtilFormatString()                               */
/*********************************************************************/
unsigned int STAFUtilFormatString2(STAFStringConst_t formatString,
                                   STAFString_t *outputString, va_list args);

/*********************************************************************/
/* STAFUtilStripPortFromEndpoint - Removes @<Port> from the end of   */
/*     an endpoint if present.                                       */
/*                                                                   */
/* Accepts: (In/Out)  A pointer to a string containing the endpoint  */
/*                    with format:                                   */
/*                      [<Interface>://<Machine Identifier>[@<Port>] */
/*          (Out)     A pointer to a string containing the stripped  */
/*                    endpoint with format:                          */
/*                      [<Interface>://<Machine Identifier>          */
/*                                                                   */
/* Returns:  0                                                       */
/* Notes  :  1) The caller is responsible for destructing the output */
/*              string containing the stripped endpoint              */
/*********************************************************************/
STAFRC_t STAFUtilStripPortFromEndpoint(STAFStringConst_t endpoint,
                                       STAFString_t *strippedEndpoint);
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.C API
:i2.Other APIs
:h3.Other APIs
:p.STAF externalizes other APIs that fall into the following general classes
:ul compact.
:li.STAFString* - Handles UTF-8 strings (#include "STAFString.h")
:li.STAFMutexSem* - Handles mutex semaphores (#include "STAFMutexSem.h")
:li.STAFEventSem* - Handles event semaphores (#include "STAFEventSem.h")
:li.STAFThread* - Handles threading support (#include "STAFThread.h" and
#include "STAFTimestamp.h")
:li.STAFDynamicLibrary* - Handles shared library / DLL support
(#include "STAFDynamicLibrary.h")
:eul.
:p.Please see the indicated header files for more information on syntax and
use of these families of APIs.
.*
.*---------------------------------------------------------------------
.*
:h2 id=c++api.C++
:p.STAF externalizes five primary classes to C++ programs.  These class are
:ul compact.
:li.STAFHandle - Handles (un)registering with STAF as well as submitting
service requests (#include "STAF.h")
:li.STAFResult - Contains the result of a STAFHandle->submit() call and some
utility functions (#include "STAF.h")
:li.STAFObject - A generic class representing a variety of object types,
including None, Strings, Lists, Maps, and Marshalling Contexts
:li.STAFObjectIterator - Handles iterating over various data structures
:li.STAFMapClassDefinition - Defines the metadata for a map class
:eul.
:p.Addtionally, these classes use several other classes which are
:ul compact.
:li.STAFString - Encapsulates UTF-8 strings (#include "STAFString.h)
:li.STAFRerPtr template - A smart-pointer class which handles memory management
(#include "STAFRefPtr.h")
:li.STAFException - The base of the STAF exception hierarchy
(#include "STAFException.h")
:eul.
:p.STAF also provides some other miscellaneous C++ classes, which are
:ul compact.
:li.STAFMutexSem and STAFMutexSemLock - Handles mutex semaphores
(#include "STAFMutexSem.h")
:li.STAFEventSem - Handles event semaphores (#include "STAFEventSem.h")
:li.STAFTimestamp - Handles times and timestamps (#include "STAFTimestamp.h")
:li.STAFDynamicLibrary - Handles shared library / DLL support
(#include "STAFDynamicLibrary.h")
:eul.
:p.In addtion, C++ applications are able to take advantage of the C-only
APIs, such as Thread support.
.*
.*---------------------------------------------------------------------
.*
:ih1.registration
:i2.STAFHandle C++ class
:ih1.C++ classes
:i2.STAFHandle
:i2.STAFResult
:h3.STAFHandle and STAFResult
:p.The STAFHandle class is used to register with, and submit service requests
to, STAF.  In C++ STAFHandles are reference counted, so they are automatically
freed for you.  To obtain a STAFHandle, you call one of the create() methods.
The first is the standard call you will use, and it allows you to specify the
name by which your program should be known.  The second create method allows
you to create a STAFHandle object from an existing STAFHandle_t which would
have been obtained from the C API STAFRegister().  By default, a STAFHandle
obtained through the first method will automatically be unregistered when the
STAFHandle is destructed.  A STAFHandle created via the second method will
not automatically be unregistered when the STAFHandle is destructed.  In either
case, you can change this behaviour with the setDoUnreg() method.
:p.Once you have a valid STAFHandlePtr, you can begin submitting requests
to STAF.  To do this, you use the submit() method, to which you specify the
machine and service which should handle the request, as well as the request
string itself.  An optional fourth parameter defines whether this will be
a synchronous or asynchronous request (if the parameter is not specified,
the request will be synchronous).  See the documentation for the C API
STAFSubmit2 for the values allowed for this parameter.
In return you get a reference counted pointer to a STAFResult
object. Again, the underlying STAFResult object will be automatically freed
when the reference count reaches zero.  The STAFResult object itself contains
a return code, rc, and a result string, result.
:p.You may examine the underlying STAFHandle_t via getHandle().  You may take
ownership of the underlying STAFHandle_t via adoptImpl().  In this latter case,
you are now responsible for the STAFHandle_t and are required to call
STAFUnRegister().  Additionally, after a call to adoptImpl(), the existing
STAFHandle object is invalidated and may not be used to call the submit() method.
:p.The utility function wrapData returns the colon-length-colon delimited
version of the specified string.  This is useful for specifying the values in
STAF request string.  See :hdref refid=ovform. for more information.
:p.The utility function stripPortFromEndpoint returns an endpoint with
the @port removed from the end of the endpoint, if present.
:p.Several utility functions are provided to handle private data that can
be specified in values in a STAF request string.
These functions are addPrivacyDelimiters, escapePrivacyDelimiters,
removePrivacyDelimiters, and maskPrivateData.
See :hdref refid=privatedata. for more information about handling private data.

:h4.Definition
:xmp.
typedef STAFRefPtr<STAFResult> STAFResultPtr;
typedef STAFRefPtr<STAFHandle> STAFHandlePtr;

class STAFResult
{
public:
    unsigned int rc;
    STAFString result;
};


class STAFHandle
{
public:
    static unsigned int create(const STAFString &name, STAFHandlePtr &handle);
    static unsigned int create(STAFHandle_t handleT, STAFHandlePtr &handle,
                               bool doUnreg = false);

    STAFResultPtr submit(const STAFString &where, const STAFString &service,
                         const STAFString &request,
                         const STAFSyncOption_t synchOption = kSTAFReqSync);

    // This returns the colon-length-colon delimited version of a string
    static STAFString wrapData(const STAFString &data);
    
    // This will format a string for you.  See STAFUtilFormatString() in
    // STAFUtil.h
    //
    // Note: DO NOT try to pass STAFString's into the ... portion of this
    //       function.  The only supported data types are "unsigned int" and
    //       STAFString_t.  Therefore be sure to call getImpl() on all
    //       STAFString's before passing them to this method.
    static STAFString formatString(STAFStringConst_t formatString, ...);
    
    // This returns the endpoint without the port (strips @nnnn from the end
    // of the endpoint, if present)
    static STAFString stripPortFromEndpoint(const STAFString &endpoint);
    
    // This method returns the data with privacy delimiters added.
    // For example, if pass in "secret", it returns "!!@secret@!!".
    static STAFString addPrivacyDelimiters(const STAFString &data);

    // This method removes any privacy delimiters from the data.
    // For example, if pass in "!!@secret@!!", it returns "secret".
    static STAFString removePrivacyDelimiters(const STAFString &data,
                                              unsigned int numLevels = 0);

    // This method masks any private data indicated by the privacy delimiters
    // by replacing the private data with asterisks.
    // For example, if pass in "!!@secret@!!", it returns "************".
    static STAFString maskPrivateData(const STAFString &data);
    
    // This method returns the data with privacy delimiters escaped.
    // For example, if pass in "!!@secret@!!", it returns "^!!@secret^@!!".
    static STAFString escapePrivacyDelimiters(const STAFString &data);
    
    STAFHandle_t getHandle();
    STAFHandle_t adoptHandle();

    bool getDoUnreg();
    void setDoUnreg(bool doUnreg);

    ~STAFHandle();
};
:exmp.
:ih1.examples
:ih2.C++ Classes
:i3.STAFHandle
:h4.Examples
:xmp keep=4.
#include "STAF.h"
#include "STAF_iostream.h"

int main(void)
{
    STAFHandlePtr handle;
    unsigned int rc  = STAFHandle&colon.&colon.create("MyApplication", handle);

    if (rc != 0)
    {
        cout << "Error registering with STAF, RC: " << rc << endl;
        return 1;
    }

    STAFResultPtr result = handle->submit("LOCAL", "PING", "PING");