HP LoadRunner Protocol SDK Test Run API Reference  12.02
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Public Member Functions | Protected Member Functions | List of all members
CApiFunctionWithNamedArguments Class Reference

The template for an API function that is declared with named arguments ("key=value"). More...

#include <ApiFunctionWithNamedArgs.h>

Inheritance diagram for CApiFunctionWithNamedArguments:
CApiFunction

Public Member Functions

 CApiFunctionWithNamedArguments (const char *mDisplayName="", int mIconId=-1)
 Instantiates CApiFunctionWithNamedArguments with the icon and display name. More...
 
virtual ~CApiFunctionWithNamedArguments ()
 Destructor.
 
void DefineStringArgument (const char *mKey, bool mIsOptional, const char *mDefaultValue="", StringArgumentValidationType mValidationCallback=NULL)
 Defines a formal string argument. More...
 
void DefineBooleanArgument (const char *mKey, bool mIsOptional, bool mDefaultValue=true, BooleanArgumentValidationType mValidationCallback=NULL)
 Defines a formal boolean argument. More...
 
void DefineNumericArgument (const char *mKey, bool mIsOptional, double mDefaultValue=0, NumericArgumentValidationType mValidationCallback=NULL)
 Defines a formal numeric argument. More...
 
const char * GetStringArgumentValue (const char *mKey) const
 Returns the value of a string argument. More...
 
bool GetBooleanArgumentValue (const char *mKey) const
 Returns the value of a boolean argument. More...
 
double GetNumericArgumentValue (const char *mKey) const
 Returns the value of a numeric argument. More...
 
bool IsSpecified (const char *mKey) const
 Checks if an argument with the specified key was passed. More...
 
- Public Member Functions inherited from CApiFunction
 CApiFunction (const char *mDisplayName="", int mIconId=-1)
 Instantiates a CApiFunction with icon and display name. More...
 
virtual ~CApiFunction ()
 Destructor.
 
int Run (const char *mStepName, va_list mVaList=0)
 Executes this API function for one step. More...
 
void WastedTime (long mMilliSeconds)
 Adds to the wasted time of all open transactions Every call to this method increases the wasted time of all open transactions, including the automatic transaction per step, if any. More...
 
void ThinkTime (long mSeconds)
 Adds to the think time of all open transactions. More...
 
void SetResultMessage (int mMessageID,...)
 Sets the message for the test result report. More...
 

Protected Member Functions

virtual void HandleArguments (va_list mVaList)
 Checks if the step arguments are valid and complete. More...
 
virtual bool CrossArgumentValidation ()
 Validates cross argument relations. More...
 
- Protected Member Functions inherited from CApiFunction
virtual void Init ()=0
 Initializations for this API function. More...
 
virtual void Invoke ()=0
 Performs the logic of the API function.
 
virtual void Terminate ()=0
 Normal termination of the API function. More...
 
virtual void Abort ()=0
 Halts the API function when an unrecoverable exception is raised. More...
 

Additional Inherited Members

- Protected Attributes inherited from CApiFunction
char * m_stepName
 The display name for the step in which this API function is called.
 
char * m_displayName
 The API function display name used in log messages and in the result report.
 
int m_iconId
 The API function icon id. The icon is used in the test result report.
 
char * m_fullName
 The name used in log messages.
 

Detailed Description

The template for an API function that is declared with named arguments ("key=value").

Class CApiFunctionWithNamedArguments extends class CApiFunction to provide a template for an API function that is declared with named arguments ("key=value"). CApiFunctionWithNamedArguments automatically handles the arguments: matching actual arguments to formal arguments, parameterization, validations, and so on. Create a class derived from CApiFunctionWithNamedArguments to implement each API function with named arguments. A function with named arguments is declared as in this example:

PROTOCOL_REPLAY_DECL_C_API int
my_function(const char * stepName, ...);

The invocation of the function specifies the arguments:

rc = my_function("MyStep", "Key1=value1", "Key2=value2", "Key3=4.5", LAST);
Note
To implement API functions declared with positional arguments, create a class derived from CApiFunction.

Constructor & Destructor Documentation

CApiFunctionWithNamedArguments::CApiFunctionWithNamedArguments ( const char *  mDisplayName = "",
int  mIconId = -1 
)

Instantiates CApiFunctionWithNamedArguments with the icon and display name.

On UNIX platforms, the icon is not supported; pass the default ID, -1.

Parameters
mDisplayNameThe step display name used in log messages and in the result report
mIconIdThe step icon ID from resource.h. The icon is used in the test result report

Member Function Documentation

virtual bool CApiFunctionWithNamedArguments::CrossArgumentValidation ( )
protectedvirtual

Validates cross argument relations.

This function handles function-specific validations. For example, sometimes it is unavoidable that the set of valid values for one argument depends on the value of another argument, or than an optional argument may be required in the case that another argument is or is not passed. If you have such a situation, implement this method to check that such constraints are met.

Returns
True if arguments are valid.
void CApiFunctionWithNamedArguments::DefineBooleanArgument ( const char *  mKey,
bool  mIsOptional,
bool  mDefaultValue = true,
BooleanArgumentValidationType  mValidationCallback = NULL 
)

Defines a formal boolean argument.

Exceptions
SDK_INTERNAL_ERRORInternal error
Parameters
mKeyArgument key
mIsOptionaltrue if the argument is optional, false if mandatory
mDefaultValueDefault value
mValidationCallbackverification callback
void CApiFunctionWithNamedArguments::DefineNumericArgument ( const char *  mKey,
bool  mIsOptional,
double  mDefaultValue = 0,
NumericArgumentValidationType  mValidationCallback = NULL 
)

Defines a formal numeric argument.

Exceptions
SDK_INTERNAL_ERRORInternal error
Parameters
mKeyArgument key
mIsOptionaltrue if the argument is optional, alse if mandatory
mDefaultValueDefault value
mValidationCallbackverification callback
void CApiFunctionWithNamedArguments::DefineStringArgument ( const char *  mKey,
bool  mIsOptional,
const char *  mDefaultValue = "",
StringArgumentValidationType  mValidationCallback = NULL 
)

Defines a formal string argument.

Exceptions
SDK_INTERNAL_ERRORInternal error
Parameters
mKeyArgument key
mIsOptionaltrue if the argument is optional, false if mandatory
mDefaultValueDefault value
mValidationCallbackverification callback
bool CApiFunctionWithNamedArguments::GetBooleanArgumentValue ( const char *  mKey) const

Returns the value of a boolean argument.

If no argument with the specified key was passed, returns the default value set in DefineBooleanArgument.

Exceptions
SDK_INTERNAL_ERRORInternal error
SDK_ACCESSING_ARG_BEFORE_PARSING_COMPLETEAccessing argument value before argument parsing is completed
SDK_ARG_NOT_FOUNDRuntime Setting argument was not found
Parameters
mKeythe argument key
double CApiFunctionWithNamedArguments::GetNumericArgumentValue ( const char *  mKey) const

Returns the value of a numeric argument.

If no argument with the specified key was passed, returns the default value set in DefineNumericArgument.

Exceptions
SDK_INTERNAL_ERRORInternal error
SDK_ACCESSING_ARG_BEFORE_PARSING_COMPLETEAccessing argument value before argument parsing is completed
SDK_ARG_NOT_FOUNDRuntime Setting argument was not found
Parameters
mKeythe argument key
const char* CApiFunctionWithNamedArguments::GetStringArgumentValue ( const char *  mKey) const

Returns the value of a string argument.

If no argument with the specified key was passed, returns the default value set in DefineStringArgument.

Exceptions
SDK_INTERNAL_ERRORInternal error
SDK_ACCESSING_ARG_BEFORE_PARSING_COMPLETEAccessing argument value before argument parsing is completed
SDK_ARG_NOT_FOUNDRuntime Setting argument was not found
Parameters
mKeythe argument key
virtual void CApiFunctionWithNamedArguments::HandleArguments ( va_list  mVaList)
protectedvirtual

Checks if the step arguments are valid and complete.

If the arguments do not pass validation, throws exception. This method is implemented by the LoadRunner infrastructure, not by the protocol developer.

Exceptions
ABORT_BY_CONTINUE_ON_ERRORTermination depends on the current value of the continue on error flag. The exception value is SDK_VERIFICATION_FAILED or SDK_CROSS_ARG_FAILED.
Parameters
mVaListvariable-length argument list

Reimplemented from CApiFunction.

bool CApiFunctionWithNamedArguments::IsSpecified ( const char *  mKey) const

Checks if an argument with the specified key was passed.

Returns
Returns true if the argument was passed to the function.
Exceptions
SDK_INTERNAL_ERRORInternal error
SDK_ACCESSING_ARG_BEFORE_PARSING_COMPLETEAccessing argument value before argument parsing is completed
SDK_ARG_NOT_FOUNDRuntime Setting argument was not found
Parameters
mKeythe argument key

The documentation for this class was generated from the following file:


Send documentation feedback to HP.


© 1995-2015 Hewlett-Packard Development Company, L.P.