API Script Generator Adapter API |
Implement this API in a script generator adapter to be used with an API Recorder Adapter. Implement the Custom Script Generator Adapter API in a script generator adapter to be used with the custom recording method.
API Script Generator Adapters implement the following calls. The shaded rows list functions that other adapter types also implement.
Identifies an API Script Generator Adapter.
BOOL IsAPISgenAdapter
();
Return TRUE to indicate that this is an API Script Generator Adapter. Any other response disables the adapter.
This adapter is associated with a single Generator Filter Adapter. When a user selects the associated Generator Filter Adapter from the Generator Filtering tab and starts an API recording session, this adapter receives any scriptable packets that are exchanged between the AUT and the target.
A C adapter should respond to this call as illustrated below.
extern "C" BOOL LINKDLL IsAPISgenAdapter() { return TRUE; }
IsAPIRecorderAdapter()
, IsAPIGenFiltExtAdapter()
Performs initialization procedures.
intInitializeScriptgen
(TCHAR *scriptPathname
);
An initialization procedure sets up the output path for scripts and can perform other startup functions.
This example illustrates a successful response.
extern "C"
int LINKDLL InitializeScriptgen (TCHAR *scriptPathname
)
{
MessageBox(NULL, "InitializeScriptgen Called","Hello from APISgen
Adapter Stub!", MB_OK);
return RSR_SUCCESS;
}
Receives an API packet for processing.
intProcessAPIPacket
(void *packet
, intIDNum
);
packet | INPUT. Pointer to a container for the name of an API packet in the session file. |
IDNum | INPUT. The API packet ID assigned by the session controller. |
The associated Generator Filter Adapter designated this packet as relevant for script generation.
This example illustrates a successful response.
extern "C" int LINKDLL ProcessAPIPacket (void *packet
, intIDNum
) { MessageBox(NULL, "ProcessAPIPacket Called","Hello from APISgen Adapter Stub!", MB_OK); return RSR_SUCCESS; {
Returns the pass completion status.
intPassComplete
(intpassNumber
);
passNumber | INPUT. The ID of the pass through the session file. |
The packets in a session file are read by the session controller and presented to the Generator Filter Adapter, which designates packets that are relevant to script generation. There are usually multiple passes through the session file.
Return RSR_SUCCESS to indicate that script generation is progressing normally. Otherwise, return a nonzero integer and supply an appropriate error message.
This example illustrates a successful response.
extern "C"
int LINKDLL PassComplete (int passNumber
)
{
MessageBox(NULL, "PassComplete Called","Hello from APISgen Adapter
Stub!", MB_OK);
return RSR_SUCCESS;
}
CheckAPIPacket()
, ProcessAPIPacket()
intGetStatus
(TCHAr *msg
, size_tmsgSize
);
msg |
Pointer to a container for the status message to be displayed. Copy the message to this location. |
msgSize |
INPUT. The size allocated for msg , which cannot exceed this size. |
Return RSR_SUCCESS to indicate that script generation is progressing normally. Otherwise, return a nonzero integer and supply an appropriate error message.
This example illustrates a successful response.
extern "C" int LINKDLLGetStatus
(TCHAR *msg
, size_tmsgSize
) { MessageBox(NULL, "GetStatus Called","Hello from APISgen Adapter Stub!", MB_OK); return RSR_SUCCESS; }
Returns configuration options in effect for this adapter.
intGetOptions
(TCHAR *options
, size_toptionsSize
);
As illustrated in the example, options supported by an adapter should be entered from a saved, local file. Otherwise, they do not persist between sessions.
The following table describes the Robot-defined configuration option arguments that a Script Generator Adapter can support. See Adapter Configuration on page 81 for a mapping of these options to the Robot GUI.
The following response indicates that this adapter:
extern "C"
int LINKDLL GetOptions
(TCHAR* options, size_t optionsSize)
{
TCHAR buf[RSR_MAX_OPTIONS];
_tcscpy(buf, _T(""));
_tcscat(buf, TEST_SCRIPT_TYPE);
_tcscat(buf, _T(","));
_tcscat(buf, _T(RSR_SCRIPT_TYPE_JAVA));
_tcscat(buf, _T(";"));
_tcscat(buf, GENERATOR_USE_DATAPOOLS);
_tcscat(buf, _T(";"));
if (_tcslen(buf) > optionsSize)
return RSR_BUFFER_TOO_SHORT;
_tcscpy(options, buf);
return RSR_SUCCESS;
}
Sets user-specified configuration options for this adapter.
intSetOptions
(TCHAR *options
, size_toptionsSize
);
options |
INPUT. Pointer to a read-only location containing the Robot user's selections. |
optionsSize |
INPUT. The size of options . |
When the user selects or specifies a value for a Robot-defined option, this call communicates the user's choice to your adapter.
For Robot-defined options pertaining to script generation (those specified on the Generator tab of the Session Record Options dialog), this call communicates the user's choices using this format:
option
[,choice][,value
]
option
is one of the option strings in column 1 of the options table: see GetOptions()
.
choice
is 0 (not checked) or 1 (checked).
value
(s) appears after a preceding comma.
For example, if your adapter supports option GENERATOR_THINK
and a user checks this option and specifies a maximum of 5 milliseconds, the options
argument of SetOptions()
contains this value: GENERATOR_THINK,1,5
. If the user does not check this option, SetOptions()
returns this value: GENERATOR_THINK,0,0
. Options are separated from one another by semicolons.
This function returns the session file name, sessionfile
, in this format:
GENERATOR_SESSION_NAME,sessionfile
You need this name in order to use the service call GetAnnotations() on page 70.
This example checks to see whether a Robot user selected the Think maximum (ms) option.
extern "C"
int LINKDLL SetOptions
(TCHAR* options, size_t optionsSize)
{
/* CStringArray declared for parsed sub-strings */
CStringArray OptionsArray;
/* parse the original string with semi-colon delimeter.*/
ParseString(options,';',&OptionsArray);
for(int i = 0;i<OptionsArray.GetSize();i++)
{
/* for every sub-string, create another CStringArray*/
CStringArray SubArray;
if(!OptionsArray.GetAt(i).IsEmpty())
{
/*parse the substrings with comma delimeters */
ParseString (OptionsArray.GetAt(i).GetBuffer
(OptionsArray.GetAt(i).GetLength()),',',&SubArray);
/* deal with each sub-string set */
if(SubArray[0]==GENERATOR_THINK)
{
if(SubArray[1] == 0)
{
int think_min = SubArray[2];
}
else
{
/* Unrecognized option -- error may be thrown*/
}
}
}
}
Session Recording Extensibility Reference | Rational Software Corporation |
Copyright (c) 2003, Rational Software Corporation | http://www.rational.com support@rational.com info@rational.com |