February 3, 2010

Server Plug-in API

Surround SCM
Server plug-ins query external reporting services, communicate information about reporting services to client plug-ins, and run requested reports. The Surround SCM and TestTrack Servers scan for plug-ins in the serverreports directory in the product application directory every 10 minutes. If a new plug-in is found, it is added to the list of available server plug-ins, which is sent to Surround SCM or TestTrack when users request to add external reports. All server plug-ins must define the following ReportStatus enumeration, which provides return values for several functions in the server plug-in API.
enum ReportStatus{
ok = 0,
failed,
hasparams
}
[toc]

GetDescription

Returns a detailed description of the server plug-in, which is used as the reporting service description in the Surround SCM or TestTrack Select Report Type dialog box. This value is expected to be different from the value returned by the GetType function but does not have to be different. void GetDescription(char * description);
ArgumentTypeDescription
descriptionchar *Output parameter. Description of reporting service. Terminate with a null character. Limited to 2048 characters. Surround SCM and TestTrack ignore extra characters. This buffer is preallocated by Surround SCM or TestTrack to 8193 bytes with 4 bytes per character for UTF-8 ((2048 chars * 4) + 1 for null terminator).

GetGUID

Returns a server plug-in GUID, which must match the compatible client plug-in GUID. If multiple server plug-ins have the same GUID, an error is returned and the first plug-in with the duplicate GUID is used. The error is written to the server log during Surround SCM or TestTrack Server start up and every time the server scans for plug-ins. 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 or TestTrack to 39 characters (38 + 1 for null terminator).
Following is an example of the required GUID format: {3F2504E0-4F89-11D3-9A0C-0305E82C3301}

GetPlugInVersion

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

GetType

Returns a description string of the server plug-in, which is used to identify the reporting service in the Select Report Type dialog box and Tools > Reports menu. void GetType(char * type);
ArgumentTypeDescription
typechar *Output parameter. Short description of reporting service (e.g., SQL Server Reporting Services). Terminate with a null character. Limited to 64 characters. Surround SCM and TestTrack ignore extra characters. This buffer is preallocated by Surround SCM or TestTrack to 257 bytes with 4 bytes per character for UTF-8 ((64 characters * 4) + 1 for null character).

GetOutputTypes

Returns an XML string that contains a list of available output formats. When users run reports, the plug-in provides a list of the available output types. void GetOutputTypes(void (*pSetFormats) (const char*));
ArgumentTypeDescription
void (*pSetFormats) (const char*)function ptrSets the XML string of output types. The const char* argument is an XML string terminated with a null character. Limited to 65535 characters. Surround SCM and TestTrack ignore extra characters.
Following is an example of an output format returned in XML format:
<outputFormat>
<id>1</id>
<description>PDF</description>
</outputFormat>
The id value is numeric and a number greater than 0, which is a reserved value. The description value is limited to 64 characters.

GetReportList

Returns an XML-formatted list of report information, including the report ID, name, title, and additional information. ReportStatus GetReportList(void (*pSetReports) (const char*), char * error);
ArgumentTypeDescription
void (*pSetReports) (const char*)function ptrSets the XML string of report information.The const char* argument is an XML string terminated with a null character. Limited to 65535 characters. Surround SCM and TestTrack ignore extra characters.
errorchar *Output parameter. Error string. Terminate with a null character. Limited to 2048 characters. Surround SCM and TestTrack ignore extra characters. This buffer is preallocated by Surround SCM or TestTrack to 8193 bytes with 4 bytes per character for UTF-8 ((2048 characters * 4) + 1 for null terminator).
Following is an example of the report information returned in XML format:
<reportinfo>
<id>1</id>
<originalName>Test Report</originalName>
<title>This is a test report</title>
<additional-info>Optional additional information goes here.</additional-info>
</reportinfo>
The name and title values are displayed in the Reports list window, Select External Reports dialog box, and the Add Report and Edit Report dialog boxes in Surround SCM and TestTrack. The additional information value is displayed in the Add Report and Edit Report dialog boxes. Following are character limits for the report information values.
  • id - 1024 characters
  • name - 32 characters
  • title - 63 characters
  • additional-info - 1024 characters

ExecuteClientCommand

Runs the commands specified in the server plug-in. enum run status ExecuteClientCommand(const char * command, void (*pSetResults) (const char*) , char * error);
ArgumentTypeDescription
commandconst char *Client command in XML. Format determined by the plug-in.
void (*pSetReports) (const char*)function ptrSets the command results in XML. Format determined by the plug-in. Const char * argument is an XML string terminated with a null character. Format determined by the plug-in. Limited to 65535 characters. Surround SCM and TestTrack ignore extra characters.
errorchar *Output parameter. Surround SCM and TestTrack Server log error text. Terminate with a null character. Limited to 2048 characters. Surround SCM and TestTrack ignore extra characters. This buffer is preallocated by Surround SCM or TestTrack to 8193 bytes with 4 bytes per character for UTF-8 (2048 characters * 4) + 1 for null terminator).
Return valueReportStatusReturns ok, failed, or hasparams.

RunReport

Runs the report in the external reporting service and returns the output file information to the Surround SCM or TestTrack Server. Surround SCM:enum status RunReport(const char * reportid, Uint32 reportOutputTypeId, const char * reserved, char * outputfile, char * error);TestTrack:enum status RunReport(const char * reportid, Uint32 reportOutputTypeId, const char * project, char * outputfile, char * error);
ArgumentTypeDescription
reportidchar *Report identified from GetReportList(). Limited to 1024 UTF-8 characters. (4096 bytes + 1 for null terminator).
reportOutputTypeIdUint32Output format identifier from GetOutputTypes().
reservedconst char *This parameter is reserved for future use (Surround SCM).
projectconst char *TestTrack project name to run the report for. Limited to 32 UTF-8 characters 128 bytes + 1 for null terminator). TestTrack use only.
outputfilechar *Output parameter. Report output file name. Must be terminated with a null character. Limited to 1024 characters. This buffer is preallocated by Surround SCM or TestTrack to 4097 bytes with 4 bytes per character for UTF-8 ((1024 characters * 4) + 1 for null terminator).
errorchar *Output parameter. Surround SCM or TestTrack Server log error text. Must be terminated with a null character. Not for Surround SCM or TestTrack Client use. Limited to 2048 characters. Surround SCM and TestTrack ignore extra characters. This buffer is preallocated by Surround SCM and TestTrack to 8193 bytes with 4 bytes per character for UTF-8 (2048 characters * 4) + 1 for null terminator).
Return valueReportStatusReturns ok, failed, or hasparams.