February 3, 2010

Client Plug-in API

Surround SCM
Client plug-ins are only required if you want to provide the following functionality from Surround SCM or TestTrack:
  • Run an external report editor to create or modify reports.
  • Run external reports that require parameters, such as filters.
Note: You cannot run external report editors or work with reports with parameters from TestTrack Web. If a client plug-in is used, a compatible server plug-in must be installed on the Surround SCM or TestTrack Server. Client and server plug-ins only work together if they have the same globally unique identifier (GUID). Surround SCM and TestTrack scan for plug-ins in the clientreports directory in the product application directory when the client starts. If a new plug-in is found, it is added to a list of available client plug-ins.

GetCapabilities

Returns the following client plug-in capabilities:
  • Run external editor - Opens an external report editor from Surround SCM or TestTrack
  • Run with parameters - Prompts users for parameters before running reports
Uint32 GetCapabilities(void);
ArgumentTypeDescription
Return valueUint32Bitmask that contains values for capabilities: run external editor (0x0001) and run with parameters (0x0002).

GetGUID

Returns a client plug-in GUID, which must match the compatible server plug-in GUID. If multiple client plug-ins have the same GUID, an error is returned and the first plug-in with the duplicate GUID is used. void GetGUID(char * guid);
ArgumentTypeDescription
guidchar *Output parameter. UUID string. Length is 38 characters. Terminate with a null character. This buffer is preallocated by Surround SCM and TestTrack to 39 characters (38 + 1 for null terminator).

GetPlugInVersion

Returns the client plug-in API version number. API version 1 is supported. Uint32 GetPluginVersion (void);
ArgumentTypeDescription
Return valueUint32Client plug-in API version number as an unsigned integer.

PrepareToRunEditor

Returns an XML string that is used to build a request to run an external report editor. The string is sent to the Surround SCM or TestTrack Server using the ExecutePluginCommand callback function. PrepareToRunEditor(void (*pSetCommand) (const char*), const char * reportid);
ArgumentTypeDescription
void (*pSetCommand) (const char*)function ptrSets the XML string command that is submitted to the Surround SCM or TestTrack Server via ExecutePluginCommand(). The const char* argument is an XML string terminated with a null character. Limited to 65535 characters. Surround SCM and TestTrack ignore extra characters.
reportidconst char *Report ID to open in the external editor. If ID is an empty string, a report is not specified and does not open when the editor opens.

RunEditor

Opens an external report editor. Any required input from the Surround SCM or TestTrack Server must be retrieved first using the PrepareToRunEditor and ExecutePluginCommand functions. void RunEditor(const char * commandResults);
ArgumentTypeDescription
commandResultsconst char *Input XML string that is a response from the Surround SCM or TestTrack Server from PrepareToRunEditor() and ExecutePlugInCommand().

PrepareToRunParameters

Returns an XML string that is used to build a request to run an external report with parameters. The string is sent to the Surround SCM or TestTrack Server using the ExecutePluginCommand callback function. void PrepareToRunParameters(void (*pSetCommand) (const char*), const char * reportid);
ArgumentTypeDescription
void (*pSetCommand) (const char*)function ptrSets the XML string command that is submitted to the Surround SCM or TestTrack Server via ExecutePluginCommand(). The const char* argument is an XML string terminated with a null character. Limited to 65535 characters. Surround and TestTrack ignore extra characters.
reportidconst char *Report ID to run.

RunParameters

Runs a report with parameters in the external reporting service. Any required input from the Surround SCM or TestTrack Server is retrieved first using the PrepareToRunParameters and ExecutePluginCommand functions. void RunParameters(const char * commandResults);
ArgumentTypeDescription
commandResultsconst char *Input XML string that is a response from the Surround SCM or TestTrack Server from PrepareToRunParameters() and ExecutePlugInCommand().