apiref.script

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

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

.*************************-START-OF-PROLOG-****************************
.*
.*  File Name          : APIRef SCRIPT
.*  Descriptive Name   : Software Test Automation Framework API Reference
.*  Detail:
.*
.*     This file contains an API Reference.
.*
.**************************-END-OF-PROLOG-*****************************
:i1.API Reference
:h1 id=apiref.API Reference
:h2 id=marshall.Marshalling Structured Data
:p.STAF supports the automatic marshalling and unmarshalling of structured data.
The act of marshalling takes a data structure and converts it into a
string-based representation.  The act of unmarshalling reverses this and
converts the string-based representation back into a data structure.
:p.STAF supports the following generic data types with its marshalling.
:ul compact.
:li.None - a unique type representing the absence of a value
:li.String - an arbitrary string value
:li.List - an ordered collection of other objects
:li.Map - an unordered collection of key/value pairs
:li.Map class - a Map with intrinsic metadata
:li.Marshalling context - represents a set of map class definitions and a
data structure defined in terms of them
:eul.
:p.Most languages support some form of the None, String, List, and Map
data types.  However, a map class and a marshalling context are likely new
concepts.
:p.A map class is really just a specialized map that is associated with a 
map class definition.  The map class definition is used to reduce the size of
a marshalling map class in comparison to a map containing the same data.  It
also contains information about how to display instances of the map class.
A map class definition contains for following information for each key
defined for a map class:
:ul compact.
:li.key -  The name of the key in the map class
:li.display-name - The display name for the key
:li.display-short-name - The short display name for the key (Optional)
:eul.
:p.You indicate that a map is an instance of a map class by setting the key
"staf-map-class-name" to the name of the map class.  And, when you unmarshall
a data structure, if you see that a map has a key called "staf-map-class-name",
you know that the map is really an instance of a map class.  You get and set
map class definitions using a marshalling context.
:p.A marshalling context is simply a container for map class definitions and
a data structure that uses (or is defined in terms of) them.  In order to
use a map class when marshalling data, you must add the map class definition
to the marshalling context, set the root object of the marshalling context to
the object you want to marshall, and then marshall the marshalling context
itself.  When you unmarshall a data structure, you will always receive a
marshalling context.  Any map class definitions referenced by map classes
within the data structure will be present in the marshalling context.
:p.When a string is unmarshalled into a data structure, it is possible that
one of the string objects that is unmarshalled is itself the string form of
another marshalled data structure.  By default, STAF will recursively
unmarshall these nested objects.  However, each language has a way to
disable these additional processing.
.*
.*---------------------------------------------------------------------
.*
:h2 id=capi.C
:p.STAF externalizes six primary APIs to C/C++ programs.  These APIs allow you
to register/unregister with STAF, submit service requests, and free the memory
associated with service request results.  In addition, STAF provides a wide
range of APIs for defining, manipulating, and marshalling data structures.
Also, STAF provides some APIs for handling private data.
:p.
:note.STAF-enabled programs written in C must be linked with the C++ compiler
(or by using any other means which allows the C++ runtime to get initialized).
Otherwise, the C++ runtime won't get a chance to initialize so the STAF
static data doesn't get initialized.  Most systems require mixed C and C++ code
to get linked by the C++ compiler.
.*
.*---------------------------------------------------------------------
.*
:ih1.registration
:i2.STAFRegister C API
:ih1.C API
:i2.STAFRegister
:h3.STAFRegister
:h4.Description
:p.The STAFRegister call is used by a C program to register with STAF.
:h4.Syntax
:xmp.
STAFRC_t STAFRegister(char *handleName, STAFHandle *handle)
:exmp.
:p.:xph.handleName:exph. points to the name by which you want this handle to
be known.
:p.:xph.handle:exph. is a pointer to the STAFHandle that will be set on
successful return from the function.  You will use this handle on all other
subsequent STAF calls.
:ih1.examples
:ih2.C/C++ API
:i3.STAFRegister
:h4.Examples
:xmp.
char *myName = "MyProgram";
STAFHandle_t myHandle = 0;
STAFRC_t rc = STAFRegister(myName, &myHandle);
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.registration
:i2.STAFRegisterUTF8 C API
:ih1.C API
:i2.STAFRegisterUTF8
:h3.STAFRegisterUTF8
:h4.Description
:p.The STAFRegisterUTF8 API is identical in all respects with STAFRegister,
except that :xph.handleName:exph. is a string in UTF-8 format.  This API is
used primarily by the Java interfaces.
.*
.*---------------------------------------------------------------------
.*
:ih1.registration
:i2.STAFUnRegister C API
:ih1.C API
:i2.STAFUnRegister
:h3.STAFUnRegister
:p.The STAFUnRegister call is used by a C program to unregister with
STAF, which frees up any internal STAF resources used by the handle.
:h4.Syntax
:xmp.
STAFRC_t STAFUnRegister(STAFHandle handle)
:exmp.
:p.:xph.handle:exph. is the handle that you received on the call to
STAFRegister.
:ih1.examples
:ih2.C API
:i3.STAFUnRegister
:h4.Examples
:xmp.
/* myHandle was previously set by STAFRegister */

STAFRC_t rc = STAFUnRegister(myHandle);
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.C API
:i2.STAFSubmit
:h3.STAFSubmit
:h4.Description
:p.The STAFSubmit call is the primary API that you will use.  It is what
allows you to submit a request to a service.
:h4.Syntax
:xmp.
STAFRC_t STAFSubmit(STAFHandle handle, char *where, char *service,
                    char *request, unsigned int requestLength,
                    char **resultPtr, unsigned int *resultLength);
:exmp.
:p.:xph.handle:exph. is the handle you received on the call to STAFRegister.
:p.:xph.where:exph. points to a string containing the destination machine for
the service request.  This should be either LOCAL or the name of a machine.
:p.:xph.service:exph. points to the name of the service to which you are
submitting the request.
:p.:xph.request:exph. points to the actual request that you are sending to the
service. This request may contain NULL (0x00) bytes.
:p.:xph.requestLength:exph. indicates the length of the request buffer passed
in.
:p.:xph.resultPtr:exph. points to a char * that will contain the address of the
result on return from the function.  If, on return from STAFSubmit,
:xph.*resultPtr:exph. is not 0, you must use STAFFree to free the result, even
if the return code from STAFSubmit was non-zero.  Note, if resultPtr is
non-zero, then the buffer that resultPtr points to will always be NULL
terminated.  However, this buffer may contain NULL (0x00) bytes, therefore, it
is not safe to determine the length of the buffer via strlen().  Instead, you
should use the length provided by :xph.resultLength:exph. below.
:p.:xph.resultLength:exph. points to an unsigned int which, on return from
STAFSubmit, will contain the length of the result buffer.
:ih1.examples
:ih2.C API
:i3.STAFSubmit
:h4.Examples
:xmp.
/* myHandle was previously set by STAFRegister */

char *someMachine = "testmach1";
char *service = "PING";
char *request = "PING";
unsigned int requestLength = strlen(request);
char *result = 0;
unsigned int resultLength = 0;
STAFRC_t rc = 0;

rc = STAFSubmit(myHandle, someMachine, service, request, requestLength,
                &result, &resultLength);
:exmp.
.*
.*---------------------------------------------------------------------
.*
:i2.STAFSubmit2
:h3 id=apiss2.STAFSubmit2
:h4.Description
:p.The STAFSubmit2 API is identical to the STAFSubmit API except that
it has an additional parameter, syncOption, which allows submission of
asynchronous requests.
:h4.Syntax
:xmp.
STAFRC_t STAFSubmit2(STAFHandle_t handle, STAFSyncOption_t syncOption,
                     char *where, char *service,
                     char *request, unsigned int requestLength,
                     char **resultPtr, unsigned int *resultLength)
:exmp.
:p.syncOption can be any of the following:
:ul compact.
:li.kSTAFReqSync - This indicates the request should be submitted synchronously.
This is equivalent to calling the STAFSubmit() API.
:li.kSTAFReqFireAndForget - This indicates the request should be submitted
asynchronously.  The request number will be passed back in the result buffer.
The request's results will not be sent to the submitter's queue nor will they
be retained by the Service service.
:li.kSTAFReqQueue - This indicates the request should be submitted
asynchronously. The request number will be passed back in the result buffer.
When the request completes, the results will be placed on the submitter's queue.
The format of this message is described below.
:li.kSTAFReqRetain - This indicates the request should be submitted
asynchronously.  The request number will be passed back in the result buffer.
The submitter can determine the results of the request by using the
:xph.FREE:exph. command of the Service service (see :hdref refid=srvreqf. for
more information).
:li.kSTAFReqQueueRetain - This indicates the request should be submitted
asynchronously.  The request number will be passed back in the result buffer.
When the request completes, the results will be placed on the submitter's queue.
The format of this message is described below.  The submitter should also free
the results of the request by using the :xph.FREE:exph. command of the Service
service (see :hdref refid=srvreqf. for more information).
:eul.
:p.The format of the queued message obtained when specifying kSTAFReqQueue or
kSTAFReqQueueRetain will be a marshalled :xph.<Map&colon.STAF/RequestComplete>:exph.
which represents the request completion information.  See table
:tref refid=STAFRequestCompleteTable. for the map class definition.
:table id='STAFRequestCompleteTable' cols='* 2* *'.
:tcap.Definition of map for "STAF/RequestComplete" type message
:tnote text='Description'.This map represents STAF/RequestComplete message information.
:thd.
:c.Key Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.requestNumber
:c.&stringObj.
:c.
:row.
:c.rc
:c.&stringObj.
:c.
:row.
:c.result
:c.&stringObj.
:c.
:etable.
:p.
For example, if you submitted the request "RESOLVE STRING {STAF/Config/OS/Name}"
to the VAR service using kSTAFReqQueue, and received a request number of 42,
then the message you would receive when the request completed might look like
:xmp.
{
  requestNumber: 42
  rc           : 0
  result       : WinNT
}
:exmp.
:p.
The queued message will always be delivered with the default priority of 5.
.*
.*---------------------------------------------------------------------
.*
:ih1.C API
:i2.STAFSubmitUTF8
:h3.STAFSubmitUTF8
:h4.Description
:p.The STAFSubmitUTF8 API is identical in all respects with STAFRegister,
except that :xph.where:exph., :xph.service:exph., :xph.request:exph.,
and :xph.*resultPtr:exph. are all strings in UTF-8 format.  This API is
used primarily by the Java interfaces.
.*
.*---------------------------------------------------------------------
.*
:ih1.C API
:i2.STAFSubmit2UTF8
:h3.STAFSubmit2UTF8
:h4.Description
:p.The STAFSubmit2UTF8 API is identical in all respects with STAFSubmit2,
except that :xph.where:exph., :xph.service:exph., :xph.request:exph.,
and :xph.*resultPtr:exph. are all strings in UTF-8 format.  This API is
used primarily by the Java interfaces.
.*
.*---------------------------------------------------------------------
.*
:ih1.C API
:i2.STAFFree
:h3.STAFFree
:h4.Description
:p.STAFFree is used to free the memory occupied by the result buffer on a call
to STAFSubmit.  You only need to call this if result buffer pointer is not zero
on return from STAFSubmit.
:h4.Syntax
:xmp.
STAFRC_t STAFFree(STAFHandle handle, char *result);
:exmp.
:p.:xph.handle:exph. is the handle you received on the call to STAFRegister.
:p.:xph.result:exph. is the pointer passed back from the STAFSubmit call.
:ih1.examples
:ih2.C API
:i3.STAFFree
:h4.Examples
:xmp.
/* myHandle was previously set by STAF     */
/* result was previously set by STAFSubmit */

STAFRC_t rc = 0;

if (result != 0) rc = STAFFree(myHandle, result);
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.C API
:i2.Data Structure and Marshalling APIs
:h3.Data Structure and Marshalling APIs
:p.STAF externalizes a wide range of APIs for defining data structures and
(un)marshaling data structures.  Here is a list of the APIs.  A later version
of this documentation will provide more details.
:xmp.
typedef enum
{
    kSTAFNoneObject               = 0,
    kSTAFScalarStringObject       = 1,
    kSTAFListObject               = 2,
    kSTAFMapObject                = 3,
    kSTAFMarshallingContextObject = 4
} STAFObjectType_t;

typedef enum
{
    kSTAFMarshallingDefaults = 0x00000000
} STAFObjectMarshallingFlags_t;


typedef enum
{
    kSTAFUnmarshallingDefaults = 0x00000000,
    kSTAFIgnoreIndirectObjects = 0x00000001
} STAFObjectUnmarshallingFlags_t;


// Object constructors/destructors
//
// Note: When a STAFObject is destructed, it recursively deletes all nested
//       objects

STAFRC_t STAFObjectConstructCopy(STAFObject_t *copy, STAFObject_t source);
STAFRC_t STAFObjectConstructReference(STAFObject_t *ref, STAFObject_t source);
STAFRC_t STAFObjectConstructNone(STAFObject_t *pNone);
STAFRC_t STAFObjectConstructScalarString(STAFObject_t *pScalar,
                                         STAFStringConst_t string);
STAFRC_t STAFObjectConstructList(STAFObject_t *list);
STAFRC_t STAFObjectConstructMap(STAFObject_t *map);
STAFRC_t STAFObjectConstructMarshallingContext(STAFObject_t *context);
STAFRC_t STAFObjectDestruct(STAFObject_t *object);

// General functions

STAFRC_t STAFObjectIsStringMarshalledData(STAFStringConst_t string,
                                          unsigned int *isMarshalledData);