Test Script Console Adapter API

prevnext

TSCA Function Reference


This section of the Test Script Console Adapter chapter provides reference information for all functions in the TSCA API. For each function, the following information is presented:

Note: The following functions are not currently used but are defined in the header file and reserved for future use.

TTCompile()
TTGetIsChild()
TTGetIsParent()
TTGetIsValidSource()
TTGetName()
TTGetParent()
TTGetType()
TTGetTypes()
TTRecord()


TTAddToSourceControl()

Adds the appropriate files for the specified test script to source control.


Syntax

HRESULT TTAddToSourceControl(const TCHAR 
SourceID[TTYPE_MAX_PATH], const TCHAR NodeID[TTYPE_MAX_ID], 
long lWindowContext, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
NodeID input. The unique ID that identifies the selected test script in the source.
lWindowContext input. A handle to a window that can be the parent of a dialog displayed by this method.
ErrorDescription output. An error description that is returned by the adapter.


Return Values

This function typically returns one of the following values:


Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTAddToSourceControl(const TCHAR 
SourceID[TTYPE_MAX_ID], const TCHAR NodeID[TTYPE_MAX_ID], long 
lWindowContext, TCHAR ErrorDescription[TTYPE_MAX_ERROR])
{
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 	 HRESULT rc = TTYPE_SUCCESS;

	 	 CConnectionContext *pContext=0;

	 	 // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 	 if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

	 	 try
	 	 {
	 	 	 /* CODE OMITTED: Retrieve assets associated with NodeID.
	 	 	 Perform add to source control on 
          assets. */

	 	 }
	 	 catch (_com_error &e)
	 	 {
	 	 	 rc = TTYPE_ERROR;
	 	 	 CString sError = (BSTR) e.Description();
	 	 	 tcscpy(ErrorDescription, (LPCTSTR) sError );
	 	 }
	 	 return eResult;
}

See Also

TTCheckIn(), TTCheckOut(), TTGetSourceControlStatus(), TTUndoCheckout()


TTCheckIn()

Checks in the appropriate files for the specified test script to source control.


Syntax

HRESULT TTCheckIn(const TCHAR SourceID[TTYPE_MAX_PATH], const 
TCHAR NodeID, long lWindowContext, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
NodeID input. The unique ID that identifies the selected test script in the source.
lWindowContext input. A handle to a window that can be the parent of a dialog displayed by this method.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTCheckIn(const TCHAR SourceID[TTYPE_MAX_ID], 
const TCHAR NodeID[TTYPE_MAX_ID], long lWindowContext, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])
{
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 	 HRESULT rc = TTYPE_SUCCESS;
	 	 CConnectionContext *pContext=0;

	 	 // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 	 if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

	 	 try
	 	 {
	 	 	 /* CODE OMITTED: Retrieve assets associated with NodeID.
	 	 	 Perform source control CheckIn on 
          assets. */

	 	 }
	 	 catch (_com_error &e)
	 	 {
	 	 	 rc = TTYPE_ERROR;
	 	 	 CString sError = (BSTR) e.Description();
	 	 	 tcscpy(ErrorDescription, (LPCTSTR) sError );
	 	 }
	 	 return rc;
}	 

See Also

TTAddToSourceControl(), TTCheckOut(), TTGetSourceControlStatus(), TTUndoCheckout()


TTCheckOut()

Checks out, from source control, the appropriate files for the specified test script.


Syntax

HRESULT TTCheckOut(const TCHAR SourceID[TTYPE_MAX_PATH], const 
TCHAR NodeID, long lWindowContext, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
NodeID input. The unique ID that identifies the selected test script in the source.
lWindowContext input. A handle to a window that can be the parent of a dialog displayed by this method.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTCheckOut(const TCHAR SourceID[TTYPE_MAX_ID], 
const TCHAR NodeID[TTYPE_MAX_ID], long lWindowContext, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])
{
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 	 HRESULT rc = TTYPE_SUCCESS;

	 	 CConnectionContext *pContext=0;

	 	 // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 	 if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

	 	 try
	 	 {
	 	 	 /* CODE OMITTED: Retrieve assets associated with NodeID.
	 	 	 Perform source control CheckOut on assets. */

	 	 }
	 	 catch (_com_error &e)
	 	 {
	 	 	 rc = TTYPE_ERROR;
	 	 	 CString sError = (BSTR) e.Description();
	 	 	 tcscpy(ErrorDescription, (LPCTSTR) sError );
	 	 }
	 	 return rc;
}	 

See Also

TTAddToSourceControl(), TTCheckIn(), TTGetSourceControlStatus(), TTUndoCheckout()


TTClearFilter()

Clears the filter for the test script source.


Syntax

HRESULT TTClearFilter(const TCHAR SourceID[TTYPE_MAX_ID], TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The handle that the client uses to identify the connection to the datastore.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTClearFilter(const TCHAR 
SourceID[TTYPE_MAX_ID], TCHAR ErrorDescription[TTYPE_MAX_ERROR])
{
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 	 HRESULT rc = TTYPE_SUCCESS;

	 	 CConnectionContext *pContext=0;

	 	 // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 	 if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

	 	 /* The following lines are for a file-based filter mechanism.
	 	 The filter buffer is first cleared, followed by replacing the
	 	 derived list of supported file extensions with *.*   */  

	 	 // Clear the filter buffer
	 	 pContext->m_sFilter = "";

	 	 pContext->m_asFilterFileExtensions.RemoveAll();
	 	 pContext->m_asFilterFileExtensions.Add("*.*");

	 	 return rc;
}

See Also

TTSetFilterEx(), TTGetFilterEx()


TTConnect()

Creates a connection to the script source identifies by the contents of the ConnectInfo paramater. It returns a handle to the client for subsequent calls to the adapter.


Syntax

HRESULT TTConnect(const char ConnectInfo[TTYPE_MAX_PATH], const 
char UserID[TTYPE_MAX_ID], ConnectOption *pConnectOptions[], 
int nOptions, char SourceID[TTYPE_MAX_ID], char 
ErrorDescription[TTYPE_MAX_ERROR])

Element Description
ConnectInfo input. Contains the data path to the test script source.
UserID input. The ID of the user to connect to the datastore.
pConnectOptions input. A pointer to the defined connect options.
nOptions input. An integer that specifies the total number of connection options.
SourceID output. The handle that TestManager uses to identify the connection to the datastore in subsequent calls to the adapter.
ErrorDescription output. An message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The data type ConnectOption is defined as:

struct ConnectOption
{
	 char Name[TTYPE_MAX_NAME];
	 char Value[TTYPE_MAX_NAME];
}ConnectOptionType;

The connection information is specified by an administrative user in the TestManager New Test Script Source property page and then passed into this function in ConnectInfo. After the connection has been established, the TSCA assigns a unique identifier for the test source to SourceID. TestManager uses this identifier for subsequent calls to the adapter to identify the connection. Be sure to document the format of this string.


Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTConnect (const char 
ConnectInfo[TTYPE_MAX_PATH], char UserID[TTYPE_MAX_ID], ConnectOption 
*pConnectOptions, int nOptions, char SourceID[TTYPE_MAX_ID], char 
ErrorDescription[TTYPE_MAX_ERROR])
{
	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 HRESULT rc = TTYPE_SUCCESS;

	 if (_tcslen(ConnectInfo) == 0)
	 {
	 	 CString sError;
	 	 sError.LoadString(IDS_EMPTY_PATH);
	 	 memset(ErrorDescription, _T('\0'), sizeof (ErrorDescription) ) ;
	 	 _tcsncpy(ErrorDescription, sError, TTYPE_MAX_ERROR - 1);
	 	 rc = TTYPE_ERROR;
	 }
	 else
	 {
	 	 CFileFind finder;
	 	 BOOL bExists = finder.FindFile(ConnectInfo);
	 	 if (!bExists)
	 	 {
	 	 	 CString sError;
	 	 	 AfxFormatString1(sError, IDS_ERROR_NOSOURCE, ConnectInfo);
	 	 	 memset(ErrorDescription, _T('\0'), sizeof (ErrorDescription);
	 	 	 _tcsncpy(ErrorDescription, sError, TTYPE_MAX_ERROR - 1);
	 	 	 rc = TTYPE_ERROR;
	 	 	 return rc;
	 	 }

	 	 // Need to go through pConnectionOption the identifier names to
	 	 // for the edit and new
	 	 CString sNewCommand = pConnectOptions[0].Value;
	 	 CString sEditCommand = pConnectOptions[1].Value;
	 	 CString sUID = pConnectOptions[2].Value;

	 	 // Generate a unique connection id for this connection context
	 	 CString sConnectionIdentifier;
	 	 GUID newGuid;
	 	 CoCreateGuid(&newGuid); 	 // note: this method is Windows-only
	 	 sConnectionIdentifier.Format("%x-%x-%x-%x%x%x%x%x%x%x%x",
	 	 	 newGuid.Data1, newGuid.Data2, newGuid.Data3,
	 	 	 newGuid.Data4[0],newGuid.Data4[1],newGuid.Data4[2],
	 	 	 newGuid.Data4[3],
	 	 	 newGuid.Data4[4],newGuid.Data4[5],newGuid.Data4[6],
	 	 	 newGuid.Data4[7] );

	 	 CConnectionContext *pExistingContext = 0;


	 	 // Not connected yet.
	 	 try
	 	 {
	 	 	 CString sUserName, sPassword;

	 	 	 //For this example, assume that connection options include
	 	 	 //the UserName and Password necessary for connecting to the
	 	 	 //datastore.

	 	 	 // Retreive the UserID and Password.
	 	 	 for (int iIndex = 0; iIndex < nOptions; iIndex++)
	 	 	 {
	 	 	 	 if (_tcsicmp(pConnectOptions[iIndex].Name, " UserName")
	 	 	 	 	 	 == 0)
	 	 	 	 {
	 	 	 	 	 sUserName = pConnectOptions[iIndex].Value;
	 	 	 	 }
	 	 	 	 else
	 	 	 	 {
	 	 	 	 	 if (_tcsicmp(pConnectOptions[iIndex].Name, "Password")
	 	 	 	 	 	 	 == 0)
	 	 	 	 	 {
	 	 	 	 	 	 sPassword = pConnectOptions[iIndex].Value;
	 	 	 	 	 }
	 	 	 	 }

	 	 	 /* CODE OMITTED: Attempt to establish a connection to test
	 	 	 script data store using the UserName and Password connection
	 	 	 options. In some cases, connecting to a data store may not
	 	 	 require any connection options.*/

	 	 	 // Store the connection context in the connection map.
	 	 	 m_ServerConnections.SetAt(sConnectionIdentifier, pContext);

	 	 	 } // for loop
	 	 catch (_com_error)
	 	 {
	 	 	 rc = TTYPE_ERROR_UNABLE_TO_CONNECT;
	 	 	 _tcscpy(ErrorDescription, (LPCTSTR) "Connection failure -
	 	 	 Bad username and Password");
	 	 }
	 } // else

	 return rc;
}

See Also

TTDisconnect()

TTDisconnect()

Disconnects from an existing script source.


Syntax

HRESULT TTDisconnect(char SourceID[TTYPE_MAX_ID], char 
ErrorDescription[TTYPE_MAX_ERROR])

Element Description
SourceID input. The handle that the client uses to identify the connection to the datastore.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

After TestManager calls TTDisconnect(), no further operations are allowed on this test script source.


Example

//********************************************************************
HRESULT TTDisconnect(const CHAR SourceID[TTYPE_MAX_ID],  CHAR 
ErrorDescription[TTYPE_MAX_ERROR])
{
	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 HRESULT rc = TTYPE_SUCCESS;

	 CConnectionContext *pContext=0;

	 // Lookup the context information for the specified SourceID.
	 CString sSourceID = SourceID;
	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 // If the context was found, then continue else indicate SourceID is
	 // invalid.
	 if (pContext)
	 {
	 /* CODE OMITTED: Disconnect from test script datastore. 
	 	 If unable to disconnect, return
	 	 TTYPE_ERROR_UNABLE_TO_DISCONNECT.*/
	 
	 }
	 else
	 	 rc = TTYPE_ERROR_INVALID_SOURCEID;

	 return rc;
}

See Also

TTConnect()


TTEdit()

Launches the editor for a specific test script.


Syntax

HRESULT TTEdit(const char SourceID[TTYPE_MAX_ID], const char 
ScriptID[TTYPE_MAX_ID], int LineNumber, ScriptOption 
*pScriptOptions[], int *nScriptOptions, char 
ErrorDescription[TTYPE_MAX_ERROR], long lWindowContext)

Element Description
SourceID input. A string that identifies the connection.
ScriptID input. A string that identifies the test script.
LineNumber input. An integer that specifies where the cursor is placed when the file is opened for editing.
pScriptOptions input. The test script options passed from TTSelect(). Any changes made to the test script options are passed back and made available to the test case or suite.
nScriptOptions input. An integer that specifies the number of test script options.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.
lWindowContext input. An integer that specifies the handle for the parent window (HWND)


Return Values

This function typically returns one of the following values:


Comments

Script options are settings that can sometimes be important for the test script to execute properly. The TSCA can specifiy and modify script options that TestManager saves as part of the test case. The data type ScriptOption is defined as:

struct ScriptOption
{
	 char Name[TTYPE_MAX_NAME];
	 char Value[TTYPE_MAX_NAME];
}ScriptOptionType;

Example

//********************************************************************
HRESULT TTEdit(const CHAR SourceID[TTYPE_MAX_ID],const CHAR 
ScriptID[TTYPE_MAX_ID], ScriptOption *pScriptOptions[], int 
*nScriptOptions, CHAR ErrorDescription[TTYPE_MAX_ERROR], long 
lWindowContext)
{
	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 HRESULT rc = TTYPE_SUCCESS;

	 CConnectionContext *pContext=0;

// Lookup the context information for the specified SourceID.
	 CString sSourceID = SourceID;
	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 // If the context was found, continue.
	 if (pContext)
	 {

	 /* CODE OMITTED: Open the test script identified by the value of
	 	 parameter ScriptID. This could be as simple as executing a
	 	 command line call to your favorite text editor or a more complex
	 	 interaction with a test tool.*/
	  
	 }
	 else
	 	 rc = TTYPE_ERROR_INVALID_SOURCEID;
	 
	 return rc;
}

See Also

TTNew(), TTShowProperties(), TTSelect()


TTExecuteNodeAction()

Executes the specified action against the specified test script.


Syntax

HRESULT TTExecuteNodeAction(const TCHAR SourceID[TT_MAX_PATH], 
const TCHAR Node[TT_MAX_ID], int nActionID, long 
lWindowContext, TCHAR ErrorDescription[TT_MAX_ERROR])


Element Description
SourceID input. The handle identifying the connection to the test script source.
Node output. The ID that identifies the selected test script in the test script source.
nActionID input. The ID of the action to be executed.
lWindowContext input. A handle to a window that can be the parent of a dialog displayed by this function.
ErrorDescription output. The message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


See Also

TTGetSourceActions(), TTGetNodeActions(), TTExecuteSourceAction()


TTExecuteSourceAction()

Executes the specified action against the test script source.


Syntax

HRESULT TTExecuteSourceAction(const TCHAR 
SourceID[TTYPE_MAX_PATH], int nActionID, long 
lWindowContext, TCHAR ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
nActionID input. The ID of the action to be executed.
lWindowContext input. A handle to a window that can be the parent of a dialog displayed by this method.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The adapter executes the specified action against the test script source.

The following structure supports this function:

#define TTYPE_ACTION_NAME     100

struct Action
{
	 char    Name[TTYPE_ACTION_NAME]:
	 int       Action ID;
} ActionType;	 	 	 

Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTExecuteSourceAction(const TCHAR 
SourceID[TTYPE_MAX_ID], int nActionID, long lWindowContext, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])
{
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 	 HRESULT rc = TTYPE_SUCCESS;

	 	 CConnectionContext *pContext=0;

	 	 // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 	 if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

	 	 switch (nActionID)
	 	  {
	 	 	 case 1:
	 	 	 	 /* CODE OMITTED: Execute custom action 1. */
	 	 	 	 	 break;
	 	 	 case 2:
	 	 	 	 /* CODE OMITTED: Execute custom action 2. */
	 	 	 	 break;

	 	 	 default:
	 	 	 	 rc = TTYPE_ERROR;
	 	 	 	 _tcscpy(ErrorDescription, _T("Unrecognized action
	 	 	 	 received"));
	 	 	 	 break;
     }
     return rc;

}

See Also

TTGetNodeActions(), TTExecuteNodeAction(), TTExecuteSourceAction()


TTGetChildren()

Returns an array of nodes that are the children of the specified node.


Syntax

HRESULT TTGetChildren(const TCHAR SourceID[TTYPE_MAX_PATH], 
const TCHAR NodeID[TTYPE_MAX_ID], struct Node 
*pChildNodes[], long *plNodeCount, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
NodeID input. The unique ID that identifies the selected test script in the source.
plChildNodes output. An array of populated Node structures, each of which is a root of the source.
plNodeCount output. The number of nodes returned by this function.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The following structure supports this function.

struct ScriptNode
{
TCHAR Name[TTYPE_MAX_NAME];
TCHAR NodeID[TTYPE_MAX_ID];
TCHAR Type[TTYPE_MAX_TYPE];
BOOL IsOnlyContainer;
BOOL IsImplementation;

};


Example

//********************************************************************
TESTTYPEAPI_API HRESULT TTGetChildren(const TCHAR 
SourceID[TTYPE_MAX_ID], const TCHAR NodeID[TTYPE_MAX_ID], struct 
ScriptNode *pChildNodes[], long* plNodeCount, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])
{
     
     AFX_MANAGE_STATE(AfxGetStaticModuleState());

     HRESULT rc = TTYPE_SUCCESS;

     CConnectionContext *pContext=0;

	 	 // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 	 if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

     // In this example, insert a single child node
	 	 *pNodeArray = new struct ScriptNode[1];
	 	 *plNodeCount = 1;
	 	 *pChildNodes = 0;

	 	 (*pNodeArray)[0].IsImplementation = TRUE;
	 	 (*pNodeArray)[0].IsOnlyContainer = FALSE;
	 	 _tcscpy((*pNodeArray)[0].Type, _T("Node"));
	 	 _tcscpy((*pNodeArray)[0].Name, sName);
     _tcscpy((*pNodeArray)[0].NodeID, _T("C:\\RootFolder\\Node"));

	 	 return rc;
}

See Also

TTGetNode(), TTGetRoots(), TTGetSourceIcon(), TTGetTypeIcon()


TTGetConfiguration()

Returns a pointer to a buffer that contains a persistable configuration for the test script source.


Syntax

HRESULT TTGetConfiguration(const TCHAR 
SourceID[TTYPE_MAX_PATH], long lWindowContext, TCHAR 
**pConfigurationBuffer, int *pnConfigurationBufferLength, 
TCHAR ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
lWindowContext input. A handle to a window that can be the parent of a dialog displayed by this method.
pConfigurationBuffer output. A pointer to the buffer that contains the streamed configuration.
pnConfigurationBufferLength output. The length of the configuration buffer.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The adapter returns the buffer configuration as a stream of characters. This data is interpreted by the adapter only.

It is assumed that the configuration buffer is allocated by the adapter and deleted by TestManager.

The adapter can display a user interface if necessary.

TestManager is responsible for persisting the data.


Example

//********************************************************************
TESTTYPEAPI_API HRESULT TTGetConfiguration(const TCHAR 
SourceID[TTYPE_MAX_ID], long lWindowContext, TCHAR 
**pConfigurationBuffer, int* pnConfigurationBufferLength, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])
{
     AFX_MANAGE_STATE(AfxGetStaticModuleState());

     HRESULT rc = TTYPE_SUCCESS;

     CConnectionContext *pContext=0;

     // lookup the context information for the specified
	 	 // SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

     if (pContext == 0)
	 	 return TTYPE_ERROR_INVALID_SOURCEID;

     *pFilterBuffer = new char[_MAX_PATH];

     CWnd ParentWnd;
	 	 ParentWnd.FromHandle((HWND)lWindowContext);

     /* You have to create a class (A dialog with an embedded
	 	 list control to perform configuration selection is used here)*/
	 	 CSelectConfigDialog Dialog(pContext, &ParentWnd);

     if (Dialog.DoModal() == IDOK)
     {
	 	 	 _tcscpy(*pConfigurationBuffer,
	 	 	 Dialog.m_sSelectedConfigurationName);
	 	 	 *pnConfigurationBufferLength =
	 	 	 Dialog.m_sSelectedConfigurationName.GetLength();
     }
     else
     {
	 	 	 // Put in blanks to indicate no filter set
	 	 	 CString sEmpty;
	 	 	 _tcscpy(*pConfigurationBuffer, sEmpty);
	 	 	 *pnConfigurationBufferLength = sEmpty.GetLength();
     }

     return rc;
}

See Also

TTSetConfiguration()


TTGetFilterEx()

Returns a buffer containing a filter for the test script source.


Syntax

HRESULT TTGetFilterEx(const TCHAR SourceID[TTYPE_MAX_PATH], 
long lWindowContext, TCHAR *pFilterBuffer, int 
*pnFilterBufferLength, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
lWindowContext input. A handle to a window that can be the parent of a dialog displayed by this method.
pFilterBuffer output. A pointer to the buffer that contains the streamed filter.
pnFilterBufferLength output. The length of the filter buffer.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The filter contained in the buffer is returned as a stream of characters.

The data is interpreted only by the adapter.

TestManager is responsible for persisting the data.

The adapter can display a user interface if desired.


Example

//********************************************************************
TESTTYPEAPI_API HRESULT TTGetFilterEx(const TCHAR 
SourceID[TTYPE_MAX_ID], long lWindowContext, TCHAR **pFilterBuffer, 
int* pnFilterBufferLength, TCHAR ErrorDescription[TTYPE_MAX_ERROR])
{
     AFX_MANAGE_STATE(AfxGetStaticModuleState());

     HRESULT rc = TTYPE_SUCCESS;

     CConnectionContext *pContext=0;

     // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

     if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

     *pFilterBuffer = new char[_MAX_PATH];

     CWnd ParentWnd;
	 	 ParentWnd.FromHandle((HWND)lWindowContext);

     /* You have to create a class (Typically a dialog with an
	 	 embedded list control to perform filter selection here) */
	 	 CSelectQueryDialog Dialog(pContext, &ParentWnd);

     if (Dialog.DoModal() == IDOK)
     {
	 	 	 _tcscpy(*pFilterBuffer, Dialog.m_sSelectedQueryName);
	 	 	  *pnFilterBufferLength =
	 	 	 Dialog.m_sSelectedQueryName.GetLength();
     }
     else
     {
	 	 	 // Put in blanks to indicate no filter set
	 	 	 CString sEmpty;
	 	 	 _tcscpy(*pFilterBuffer, sEmpty);
	 	 	 *pnFilterBufferLength = sEmpty.GetLength();
     }

     return rc;
}

See Also

TTSetFilterEx()


TTGetIcon()

Returns the path of the bitmap that represents test scripts in the source.


Syntax

HRESULT TTGetIcon(const char SourceID[TTYPE_MAX_ID], char 
IconPath[TTYPE_MAX_PATH], char 
ErrorDescription[TTYPE_MAX_ERROR])

Element Description
SourceID input. A string that identifies the connection.
IconPath output. A string that specifies the path where the image file of the icon is located. The file must contain a 16 x 16 bitmap image.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Example

//********************************************************************
TESTTYPEAPI_API HRESULT TTGetIcon(char SourceID[TTYPE_MAX_ID], char 
IconPath[TTYPE_MAX_PATH], char ErrorDescription[TTYPE_MAX_ERROR])
{
	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 HRESULT rc = TTYPE_SUCCESS;

	 DWORD	 dwError;
	 CString sIcon;
	 char	  szModuleFileName[_MAX_PATH+1];
	 char	  szModuleFilePath[_MAX_PATH+1];
	 char	  szDir[_MAX_DIR+1];
	 char	  szDrive[_MAX_DRIVE+1];

	 // In this sample, the icon is assumed to be in the same location as
	 // the adapter
	 dwError=GetModuleFileName((HMODULE)AfxGetInstanceHandle(),
	 szModuleFileName, _MAX_PATH);
	 _splitpath(szModuleFileName, szDrive, szDir, NULL, NULL);
	 	 
	 _tcscpy(szModuleFilePath, szDrive);
	 _tcscat(szModuleFilePath, szDir);

	 sIcon.LoadString(IDS_ICON_NAME);
	 _tcscat(szModuleFilePath, sIcon);
	 _tcscpy(IconPath, szModuleFilePath);

	 return rc;
}

See Also

TTEdit(), TTNew()


TTGetIsFunctionSupported()

Indicates whether a specified function is supported by the adapter for an active connection.


Syntax

HRESULT TTGetIsFunctionSupported(const TCHAR 
SourceID[TTYPE_MAX_PATH], long lFunctionID, BOOL 
*pbSupported, TCHAR ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
lFunctionID input. The constant definition of the function.
pbSupported, output. A Boolean indicating whether the specified function is supported.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

Following are the values for the parameter lFunctionID:

TTYPE_FUNCTION_TTAddToSourceControl
TTYPE_FUNCTION_TTCheckIn
TTYPE_FUNCTION_TTCheckOut
TTYPE_FUNCTION_TTCompile
TTYPE_FUNCTION_TTConnect
TTYPE_FUNCTION_TTDisconnect
TTYPE_FUNCTION_TTEdit
TTYPE_FUNCTION_TTExecuteNodeAction
TTYPE_FUNCTION_TTExecutionSourceAction
TTYPE_FUNCTION_TTGetChildren
TTYPE_FUNCTION_TTGetConfiguration
TTYPE_FUNCTION_TTGetFilterEx
TTYPE_FUNCTION_TTGetIcon
TTYPE_FUNCTION_TTGetName
TTYPE_FUNCTION_TTGetNode
TTYPE_FUNCTION_TTGetNodeActions
TTYPE_FUNCTION_TTGetRoots
TTYPE_FUNCTION_TTGetSourceActions
TTYPE_FUNCTION_TTGetSourceControlStatus
TTYPE_FUNCTION_TTGetSourceIcon
TTYPE_FUNCTION_TTGetTestToolOptions
TTYPE_FUNCTION_TTGetTypeIcon
TTYPE_FUNCTION_TTNew
TTYPE_FUNCTION_TTRecord
TTYPE_FUNCTION_TTSelect
TTYPE_FUNCTION_TTSetConfiguration
TTYPE_FUNCTION_TTSetFilterEx
TTYPE_FUNCTION_TTShowProperties
TTYPE_FUNCTION_TTUndoCheckOut

Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTGetIsFunctionSupported(const TCHAR 
SourceID[TTYPE_MAX_ID], const TCHAR NodeID[TTYPE_MAX_ID], long 
lFunctionID, BOOL *pbIsSupported, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])
{
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 	 /* The following is a sample for a minimal adapter with no source
	 	 control support. */

	 	 switch (lFunctionID)
	 	 {
	 	 	 case TTYPE_FUNCTION_TTConnect:
	 	 	 case TTYPE_FUNCTION_TTDisconnect:
	 	 	 case TTYPE_FUNCTION_TTEdit:
	 	 	 case TTYPE_FUNCTION_TTGetIcon:
	 	 	 case TTYPE_FUNCTION_TTGetName:
	 	 	 case TTYPE_FUNCTION_TTNew:
	 	 	 case TTYPE_FUNCTION_TTRecord:
	 	 	 case TTYPE_FUNCTION_TTSelect:
	 	 	 case TTYPE_FUNCTION_TTShowProperties:
	 	 	 	 *pbIsSupported = TRUE;
	 	 	 	 break;

	 	 	 default:
	 	 	 	 *pbIsSupported = FALSE;
	 	 	 	 break;
	 	 }

	 	 return TTYPE_SUCCESS;
}

TTGetName()

Returns the name of the specified test script.


Syntax

HRESULT TTGetName(const char SourceID[TTYPE_MAX_ID], const char 
ScriptID[TTYPE_MAX_ID], char ScriptName[TTYPE_MAX_ID], char 
ErrorDescription[TTYPE_MAX_ERROR])

Element Description
SourceID input. A string that identifies the connection.
ScriptID input. A string that identifies the test script.
ScriptName output. A string that specifies the name of a test script.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns on of the following values:


Example

//********************************************************************
HRESULT TTGetName(const CHAR SourceID[TTYPE_MAX_ID], const CHAR 
ScriptID[TTYPE_MAX_ID], CHAR ScriptName[TTYPE_MAX_NAME], CHAR 
ErrorDescription[TTYPE_MAX_ERROR])
{
	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 HRESULT rc = TTYPE_SUCCESS;

	 CString sScriptName;

	 /* CODE OMITTED: Obtain name of script and store in variable
	 	 sScriptName.*/ 

	 _tcscpy(ScriptName, sScriptName);

	 return rc;
}


See Also

TTEdit(), TTProperties()


TTGetNode()

Returns information about the node that is identified by the unique ID.


Syntax

HRESULT TTGetNode(const TCHAR SourceID[TTYPE_MAX_PATH], const 
TCHAR NodeID[TTYPE_MAX_ID], struct ScriptNode **pNode, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
NodeID input. The unique ID that identifies the selected test script in the source.
pNode output. A pointer to a populated ScriptNode structure.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The following structure supports this function.

struct ScriptNode
{
      TCHAR  Name[TTYPE_MAX_NAME];
      TCHAR  NodeID[TTYPE_MAX_ID];
      TCHAR  Type[TTYPE_MAX_TYPE];
      BOOL   IsOnlyContainer;
      BOOL   IsImplementation;
};

Example

//********************************************************************
TESTTYPEAPI_API HRESULT TTGetNode(const TCHAR SourceID[TTYPE_MAX_ID], 
const TCHAR NodeID[TTYPE_MAX_ID], struct ScriptNode** pNode, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])
{
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 	 HRESULT rc = S_OK;
	 	 *pNode = 0;

	 	 CConnectionContext *pContext=0;

	 	 // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 	 if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

	 	 *pNode = new struct ScriptNode;

	 	 // This adapter example is assuming that there is not a node
	 	 // hierarchy.
	 	 _tcsncpy((*pNode)->Name, (const char *)NodeID, TTYPE_MAX_NAME);

	 	 (*pNode)->IsOnlyContainer = FALSE;
	 	 (*pNode)->IsImplementation = TRUE;

	 	 _tcscpy((*pNode)->NodeID, NodeID);

     // copy the name of node type into the node structure for all
	 	 // nodes
	 	 _tcscpy((*pNode)->Type, pContext->m_sType);

return rc;
}

See Also

TTGetChildren(), TTGetNodeActions(), TTGetSourceControlStatus(), TTGetTypeIcon()


TTGetNodeActions()

Returns a pointer to an array of test script actions.


Syntax

HRESULT TTGetNodeActions(const TCHAR SourceID[TT_MAX_PATH], 
const TCHAR Type[TT_MAX_TYPE], struct Action *pActions[], 
int *pnActionCount, TCHAR ErrorDescription[TT_MAX_ERROR])


Element Description
SourceID input. The handle identifying the connection to the test script source.
Type input. The name of a node type.
pActions output. A local array containing action structures for node Type.
pnActionCount output. The number of actions in pActions.
ErrorDescription output. The message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The Type parameter is empty if no types have been returned.


See Also

TTGetSourceActions(), TTExecuteNodeAction(), TTExecuteSourceAction()


TTGetRoots()

Returns the array of nodes comprising the roots of the test script source.


Syntax

HRESULT TTGetRoots(const TCHAR SourceID[TTYPE_MAX_PATH], struct 
Node *pRootNodes[], long *plNodeCount, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
pRootNodes output. A handle to a window that can be the parent of a dialog displayed by this method.
plNodeCount output. The number of nodes returned by this method.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The following structure supports this function.

struct ScriptNode
{
      	 CHAR	 	 	 Name[TTYPE_MAX_NAME];
      	 TCHAR	 	 	 NodeID[TTYPE_MAX_ID];
      	 TCHAR	 	 	 Type[TTYPE_MAX_TYPE];
      	 BOOL	 	 	 IsOnlyContainer;
      	 BOOL	 	 	 IsImplementation;
};

Example

//********************************************************************
TESTTYPEAPI_API HRESULT TTGetRoots(const TCHAR SourceID[TTYPE_MAX_ID], 
struct ScriptNode *pRootNodes[], long* plNodeCount, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])
{
     
     AFX_MANAGE_STATE(AfxGetStaticModuleState());

     HRESULT rc = TTYPE_SUCCESS;

     CConnectionContext *pContext=0;

     // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

     if (pContext == 0)
          return TTYPE_ERROR_INVALID_SOURCEID;

     // In this example, insert a single folder as a root node
	 	 *pNodeArray = new struct ScriptNode[1];
	 	 *plNodeCount = 1;
	 	 *pChildNodes = 0;

	 	 *pNodeArray)[0].IsImplementation = FALSE;
	 	 (*pNodeArray)[0].IsOnlyContainer = TRUE;
	 	 _tcscpy((*pNodeArray)[0].Type, _T("RootFolder"));
	 	 _tcscpy((*pNodeArray)[0].Name, sName);
	 	 _tcscpy((*pNodeArray)[0].NodeID, _T("C:\\RootFolder\\"));

	 	 return rc;
}

See Also

TTGetChildren(), TTGetNode(), TTGetSourceControlStatus(), TTGetTypeIcon()


TTGetSourceActions()

Returns a pointer to an array of actions that can be applied to the test script source.


Syntax

HRESULT TTGetSourceActions(const TCHAR 
SourceID[TTYPE_MAX_PATH], struct Action *pActions[], long 
*plActionCount, TCHAR ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
pActions output. An array of populated Action structures, each of which defines an action.
plActionCount output. The number of actions returned.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The adapter returns an array of actions that apply to the test script source.

It is assumed that the action array is allocated by the adapter and deleted by TestManager.

The following structure supports this function:

#define TTYPE_ACTION_NAME     100

struct Action
{
	 char    Name[TTYPE_ACTION_NAME]:
	 int       ActionID;
} ActionType;	 	 	 

Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTGetSourceActions(const TCHAR 
SourceID[TTYPE_MAX_ID], struct TTAction *pActions[], int 
*pnActionCount, TCHAR ErrorDescription[TTYPE_MAX_ERROR])
{
     AFX_MANAGE_STATE(AfxGetStaticModuleState());

     HRESULT rc = TTYPE_SUCCESS;

     CConnectionContext *pContext=0;

     // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);
     
     if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

     *pActions = new TTAction[2];

     _tcscpy((*pActions)[0].Name, _T("Custom Action 1"));
	 	 ((*pActions)[0].ActionID = 1

     _tcscpy((*pActions)[1].Name, _T("Custom Action 2"));
	 	 ((*pActions)[1].ActionID = 2

     return rc;

}

See Also

TTExecuteNodeAction(), TTGetNodeActions(), TTExecuteSourceAction()


TTGetSourceControlStatus()

Returns the current source-control status of the test script.


Syntax

HRESULT TTGetSourceControlStatus(const TCHAR 
SourceID[TTYPE_MAX_PATH], const TCHAR NodeID, long 
*p1Status, TCHAR ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
NodeID input. The unique ID that identifies the selected test script in the source.
p1Status output. The returned source control status of the specified test script source:

TTYPE_SCSTATUS_NOTCONTROLLED. The source file is not under source control.

TTYPE_SCSTATUS_CHECKEDOUT. The source file is checked out.

TTYPE_SCSTATUS_CHECKEDIN. The source file is checked in.

ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTGetSourceControlStatus(const TCHAR 
SourceID[TTYPE_MAX_ID], const TCHAR NodeID[TTYPE_MAX_ID], long 
*plStatus, TCHAR ErrorDescription[TTYPE_MAX_ERROR])
{
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 	 HRESULT rc = TTYPE_SUCCESS;
	 	 CConnectionContext *pContext=0;

	 	 // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 	 if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

	 	 try
	 	 {
	 	 	 long lResult;

	 	 	 /* CODE OMITTED: Retrieve assets associated with NodeID.
	 	 	 Retrieve source control status on assets and set lResult
	 	 	 accordingly. */
          
	 	 	 *plStatus = lResult;

	 	 }
	 	 catch (_com_error &e)
	 	 {
	 	 	 rc = TTYPE_ERROR;
	 	 	 CString sError = (BSTR) e.Description();
	 	 	 tcscpy(ErrorDescription, (LPCTSTR) sError );
	 	 }
	 	 return rc;
}	 

See Also

TTAddToSourceControl(), TTCheckIn(), TTCheckOut(), TTUndoCheckout()


TTGetSourceIcon()

Returns the path to the icon that represents the test script source.


Syntax

HRESULT TTGetSourceIcon(const TCHAR SourceID[TTYPE_MAX_PATH], 
TCHAR IconPath[TTYPE_MAX_PATH], TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
IconPath input. The path to the icon that represents the test script source.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTGetSourceIcon(const TCHAR 
SourceID[TTYPE_MAX_ID], TCHAR IconPath[TTYPE_MAX_PATH], TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])
{
	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 HRESULT rc = TTYPE_SUCCESS;

	 DWORD	 dwError;
	 CString sIcon;
	 char	  szModuleFileName[_MAX_PATH+1];
	 char	  szModuleFilePath[_MAX_PATH+1];
	 char	  szDir[_MAX_DIR+1];
	 char	  szDrive[_MAX_DRIVE+1];

	 // In this sample, the icon is assumed to be in the same location
	 // as the adapter
	 dwError=GetModuleFileName((HMODULE)AfxGetInstanceHandle(),
	 szModuleFileName, _MAX_PATH);
	 _splitpath(szModuleFileName, szDrive, szDir, NULL, NULL);
	 	 
	 _tcscpy(szModuleFilePath, szDrive);
	 _tcscat(szModuleFilePath, szDir);

	 sIcon.LoadString(IDS_SOURCE_ICON);
	 _tcscat(szModuleFilePath, sIcon);
	 _tcscpy(IconPath, szModuleFilePath);

	 return rc;
}

See Also

TTGetChildren(), TTGetNode(), TTGetIcon(), TTGetTypeIcon()


TTGetTestToolOptions()

Returns the test tool options associated with the specified test script.


Syntax

HRESULT TTGetTestToolOptions(const TCHAR 
SourceID[TTYPE_MAX_PATH], const TCHAR NodeID[TTYPE_MAX], 
long lWindowContext, struct ScriptOption *pOptions[], int 
*piCount, TCHAR ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
NodeID input. The unique ID that identifies the selected test script in the source.
lWindowContext input. A handle to a window that can be the parent of a dialog displayed by this method.
pOptions output. An array of adapter-provided test tool options.
piCount output. The number of test tool options.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The adapter returns an array of name-value pairs containing the test tool options for the specified test script.


Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTGetTestToolOptions(const TCHAR 
SourceID[TTYPE_MAX_ID], const TCHAR NodeID[TTYPE_MAX_ID], long 
lWindowContext, struct ScriptOption *pOptions[], int* piCount, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR]);
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState())
{
	 	 HRESULT rc = TTYPE_SUCCESS;

	 	 CConnectionContext *pContext=0;

	 	 // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 	 if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

	 	 try
	 	 {
	 	 	 long lResult;

	 	 	 /* In this example, the username and password are provided as
	 	 	 connection options.  They are needed for the test tool as well,
	 	 	 but in a slightly different format. */

	 	 	 CString sUserName;
	 	 	 CString sPassword;
	 	 	 // Retrieve the UserID and Password 
	 	 	 for (int iIndex = 0; iIndex < nOptions; iIndex++)
	 	 	 {
	 	 	 	 if (_tcsicmp(pConnectOptions[iIndex].Name, " UserName")
	 	 	 	 == 0)
	 	 	 	 {
	 	 	 	 	 sUserName = pConnectOptions[iIndex].Value;
	 	 	 	 }
	 	 	 	 else
	 	 	 	 if (_tcsicmp(pConnectOptions[iIndex].Name, "Password")
	 	 	 	 == 0)
	 	 	 	 {
	 	 	 	 	 sPassword = pConnectOptions[iIndex].Value;
	 	 	 	 }
	 	 	 }

	 	 	 *pOptions = new ScriptOption[ 2 ];
	 	 	 *piCount = 2;

	 	 	 _tcscpy((*pOptions)[0].Name, _T("USR"));
	 	 	 _tcscpy((*pOptions)[0].Value, sUserName);

	 	 	 _tcscpy((*pOptions)[0].Name, _T("PSWD"));
	 	 	 _tcscpy((*pOptions)[0].Value, sPassword);

	 	 }
	 	 catch (_com_error &e)
	 	 {
	 	 	 rc = TTYPE_ERROR;
	 	 	 CString sError = (BSTR) e.Description();
	 	 	 tcscpy(ErrorDescription, (LPCTSTR) sError );
	 	 }
	 	 return rc;
}

TTGetTypeIcon()

Returns the path to the bitmap that represents the node type.


Syntax

HRESULT TTGetTypeIcon(const TCHAR SourceID[TTYPE_MAX_PATH], 
const TCHAR Type[TTYPE_MAX_TYPE], TCHAR 
IconPath[TTYPE_MAX_PATH], TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
Type input. The type of node for which the icon is being requested.
IconPath input. The path to the icon that represents the test script type.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The following structure supports this function.

struct ScriptNode
{
      TCHAR  Name[TTYPE_MAX_NAME];
      TCHAR  NodeID[TTYPE_MAX_ID];
      TCHAR  Type[TTYPE_MAX_TYPE];
      BOOL   IsOnlyContainer;
      BOOL   IsImplementation;
};

Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTGetTypeIcon(const TCHAR 
SourceID[TTYPE_MAX_ID], const TCHAR Type[TTYPE_MAX_TYPE], TCHAR 
IconPath[TTYPE_MAX_PATH], TCHAR ErrorDescription[TTYPE_MAX_ERROR])
{
	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 HRESULT rc = TTYPE_SUCCESS;

	 DWORD	 dwError;
	 CString sIcon;
	 char	  szModuleFileName[_MAX_PATH+1];
	 char	  szModuleFilePath[_MAX_PATH+1];
	 char	  szDir[_MAX_DIR+1];
	 char	  szDrive[_MAX_DRIVE+1];

	 // In this sample, the icon is assumed to be in the same location
	 // as the adapter.
	 dwError=GetModuleFileName((HMODULE)AfxGetInstanceHandle(),
	 szModuleFileName, _MAX_PATH);
	 _splitpath(szModuleFileName, szDrive, szDir, NULL, NULL);
	 	 
	 _tcscpy(szModuleFilePath, szDrive);
	 _tcscat(szModuleFilePath, szDir);

	 sIcon.LoadString(IDS_TYPE_ICON);
	 _tcscat(szModuleFilePath, sIcon);
	 _tcscpy(IconPath, szModuleFilePath);

	 return rc;
}

See Also

TTGetChildren(), TTGetNode(), TTGetRoots()


TTNew()

Enables the tester to create a new test script using the hosted tool.


Syntax

HRESULT TTNew(const char SourceID[TTYPE_MAX_ID], char 
ScriptID[TTYPE_MAX_ID], char Name[TTYPE_MAX_NAME], 
ScriptOption *pScriptOptions[], int* nScriptOptions, char 
ErrorDescription[TTYPE_MAX_ERROR], long lWindowContext)

Element Description
SourceID input. A string that identifies the test source.
ScriptID output. A string that identifies the test script.
Name output. A string that specifies the name of a test script.
pScriptOptions output. Reserved for future use.
nScriptOptions output. Reserved for future use.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.
lWindowContext input. An integer that specifies the handle for the parent window (HWND).


Return Values

This function typically returns one of the following values:


Comments

After the tester creates the new test script, this function passes the ID and test script name to Test Manager. TestManager then passes this information to the TTEdit() and TTShowProperties() functions of this adapter as well as to the Test Script Execution Adapter (TSEA).


Example

//********************************************************************
HRESULT TTNew(const CHAR SourceID[TTYPE_MAX_ID], CHAR ScriptID 
[TTYPE_MAX_ID], CHAR Name[TTYPE_MAX_NAME], ScriptOption 
*pScriptOptions[], int* nScriptOptions, CHAR 
ErrorDescription[TTYPE_MAX_ERROR], long lWindowContext)
{
	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 HRESULT rc = TTYPE_SUCCESS;

	 CConnectionContext *pContext=0;

	 // Lookup the context information for the specified SourceID.
	 CString sSourceID = SourceID;
	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 // If the context was found, continue.
	 if (pContext)
	 {

	 	 /* CODE OMITTED: Create a new Test Script.  This could be as
	 	  simple as executing a command line call to your favorite text
	 	  editor or a more complex interaction with a Test Tool.*/ 
	 
	 	  /* The Name and ID of the new script must be
	 	 	 returned in the variables ScriptID and ScriptName.*/
	 
	 	 _tcscpy(ScriptID, (const char *)sScriptID);
	 	 _tcscpy(ScriptName, (const char *)sScriptName);

	 }
	 else
	 	 rc = TTYPE_ERROR_INVALID_SOURCEID;
	 
	 return rc;
}

See Also

TTEdit(), TTShowProperties()


TTSelect()

Displays a UI that allows a user to select a test script and then returns information that identifies the selected script.


Syntax

HRESULT TTSelect(const char SourceID[TTYPE_MAX_ID], char 
ScriptID[TTYPE_MAX_ID], char ScriptName[TTYPE_MAX_ID], 
ScriptOption *pScriptOptions[], int* nScriptOptions, char 
ErrorDescription[TTYPE_MAX_ERROR], long lWindowContext)

Element Description
SourceID input. A string that identifies the connection.
ScriptID output. A string that identifies the test script.
ScriptName output. A string that specifies the name of a test script.
pScriptOptions output. A structure that specifies options for running the test script.
nOptionOptions output. An integer that specifies the number of test script options.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.
lWindowContext input. An integer that specifies the handle for the parent window (HWND)


Return Values

This function typically returns one of the following values:


Comments

Use this function to provide a UI for the user to select a test script. The function returns the ID and name of the test script to TestManager. These parameters are passed to the TTEdit() and TTShowProperties() functions and are also passed to the Test Script Execution Adapter (TSEA).

Script options are settings that may be important for the test script to execute properly. The TSCA can specify and modify script options, which are saved by TestManager as part of the test case or suite. The data type ScriptOption is defined as follows:

struct ScriptOption
{
	 char Name[TTYPE_MAX_NAME];
	 char Value[TTYPE_MAX_NAME];
}ScriptOptionType;

Example

//********************************************************************
TESTTYPEAPI_API HRESULT TTSelect(const char SourceID[TTYPEMAX_ID], 
char ScriptID[TTYPE_MAX_ID], char ScriptName[TTYPE_MAX_NAME], 
ScriptOption *pScriptOptions[], int *nScriptOptions, char 
ErrorDescription[TTYPE_MAX_ERROR], long lWindowContext)
{
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 	 HRESULT rc = TTYPE_SUCCESS;

	 	 CConnectionContext *pContext=0;

 	 // lookup the context information for the specified SourceID
	 m_ServerConnections.Lookup(SourceID, (void *&)pContext);
	 
  	 // if the context was found, then continue
	 if (pContext)
	 {
	 	 // remove the connection from the list of "live" connections
	 	 m_ServerConnections.RemoveKey(SourceID);
	 	 // Now delete it
	 	 delete pContext;
	 }

	 return rc;
}

See Also

TTEdit(), TTShowProperties()


TTSetConfiguration()

Sets the configuration for the test script source based on the specified configuration buffer.


Syntax

HRESULT TTSetConfiguration(const TCHAR 
SourceID[TTYPE_MAX_PATH], TCHAR *pConfigurationBuffer, int 
nConfigurationBufferLength, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
pConfigurationBuffer input. A pointer to the buffer that contains the streamed configuration.
nConfigurationBufferLength input. The length of the configuration buffer.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The adapter sets the configuration for the test script source.

TestManager passes the data returned by a previous call to the method TTGetConfiguration() as an input parameter.


Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTSetConfiguration(const TCHAR 
SourceID[TTYPE_MAX_ID], TCHAR *pConfigurationBuffer, int 
nConfigurationBufferLength, TCHAR ErrorDescription[TTYPE_MAX_ERROR])
{
     AFX_MANAGE_STATE(AfxGetStaticModuleState());

     HRESULT rc = TTYPE_SUCCESS;

     CConnectionContext *pContext=0;

     // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);
     
     if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

	 	 // Persist the raw filter buffer for possible future use by
	 	 // TTGetConfigurationEx or TTCompile, TTEdit, etc...
	 	 pContext->m_sConfiguration = pConfigurationBuffer;

     /* CODE OMITTED: Handle any configuration application actions
	 	 needed by the adapter */

     return rc;
}

See Also

TTGetConfiguration()


TTSetFilterEx()

Sets the filter for the test script source based on the specified filter buffer.


Syntax

HRESULT TTSetFilterEx(const TCHAR SourceID[TTYPE_MAX_PATH], 
TCHAR *pFilterBuffer, int nFilterBufferLength, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
pFilterBuffer input. A pointer to the buffer that contains the streamed filter.
nFilterBufferLength input. The length of the filter buffer.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Comments

The adapter sets the filter for the test script source.

TestManager passes, as an input parameter, the data returned by a previous call to the method TTGetFilterEx.


Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTSetFilterEx(const TCHAR 
SourceID[TTYPE_MAX_ID], TCHAR *pFilterBuffer, int nFilterBufferLength, 
TCHAR ErrorDescription[TTYPE_MAX_ERROR])
{
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 	 HRESULT rc = TTYPE_SUCCESS;

	 	 CConnectionContext *pContext=0;

	 	 // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);
     
	 	 if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

	 	 /* The remainder of this code is an example of filtering file
	 	 based script source. In this sample, the TTGetFilterEx returned
	 	 a list of file extensions that were to be hidden from the user.
	 	 This example merely parses the filter buffer and
	 	 stores the results in the adapter's connection context.
	 	 TTGetRoots and TTGetChildren
	 	 would then use this to determine their output. */

	 	 // Persist the raw filter buffer for possible future use by
	 	 // TTGetFilterEx
	 	 pContext->m_sFilter = pFilterBuffer;

	 	 TCHAR szBuffer[512];
	 	 _tcscpy(szBuffer, pFilterBuffer);
	 	 char seps[] = ";";
	 	 char *token;

     pContext->m_asFilterFileExtensions.RemoveAll();

	 	 // establish string and get the first token:
	 	 token = strtok(szBuffer, seps );
	 	 while( token != NULL )
	 	 {
	 	 	 CString sToken = token;
	 	 	 sToken.TrimLeft();
	 	 	 sToken.TrimRight();
	 	 	 pContext->m_asFilterFileExtensions.Add(sToken);
	 
	 	 // Get next token:
	 	 token = strtok( NULL, seps );

     }  //  end while

     return rc;
}

See Also

TTGetFilterEx()


TTShowProperties()

Displays the properties of a test script.


Syntax

HRESULT TTShowProperties(const char SourceID[TTYPE_MAX_ID], 
const char ScriptID[TTYPE_MAX_ID], ScriptOption 
*pScriptOptions[], int *nScriptOptions, char 
ErrorDescription[TTYPE_MAX_ERROR], long lWindowContext)

Element Description
SourceID input. A string that identifies the connection.
ScriptID input. A string that identifies the test script.
pScriptOptions input.The test script options passed in from TTSelect(). Any changes made to the test script options must be passed back and made available to the test case or suite.
nScriptOptions input. An integer that specifies the number of test script options.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.
lWindowContext input. An integer that specifies the handle for the parent window (HWND)


Return Values

This function typically returns one of the following values:


Comments

Script options are settings that may be important for the test script to execute properly. The TSCA can specifiy and modify script options, which are saved by TestManager as part of the test case or suite. The data type ScriptOption is defined as follows:

struct ScriptOption
{
	 char Name[TTYPE_MAX_NAME];
	 char Value[TTYPE_MAX_NAME];
}ScriptOptionType;

Example

//********************************************************************
HRESULT TTShowProperties(const CHAR SourceID[TTYPE_MAX_ID],const CHAR 
ScriptID [TTYPE_MAX_ID], ScriptOption 
*pScriptOptions[], int nScriptOptions, long lWindowContext , char 
ErrorDescription[TTYPE_MAX_ERROR])
{
	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 HRESULT rc = TTYPE_SUCCESS;

	 CConnectionContext *pContext=0;

	 // Lookup the context information for the specified SourceID.
	 CString sSourceID = SourceID;
	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 // If the context was found, continue.
	 if (pContext)
	 {

	 /* CODE OMITTED: Display the test script property sheet.*/ 
	 
	 }
	 else
	 	 rc = TTYPE_ERROR_INVALID_SOURCEID;
	 
	 return rc;
}


See Also

TTSelect(), TTEdit()


TTUndoCheckout()

Undoes the checkout of the appropriate files for the specified test script.


Syntax

HRESULT TTUndoCheckout(const TCHAR SourceID[TTYPE_MAX_PATH], 
const TCHAR NodeID, long lWindowContext, TCHAR 
ErrorDescription[TTYPE_MAX_ERROR])


Element Description
SourceID input. The adapter-provided handle that identifies the connection to the test script source.
NodeID input. The unique ID that identifies the selected test script in the source.
lWindowContext input. A handle to a window that can be the parent of a dialog displayed by this method.
ErrorDescription output. A message to be displayed to the TestManager user if there is an error.


Return Values

This function typically returns one of the following values:


Example

//*******************************************************************
TESTTYPEAPI_API HRESULT TTUndoCheckOut(const TCHAR 
SourceID[TTYPE_MAX_ID], const TCHAR NodeID[TTYPE_MAX_ID], long 
lWindowContext, TCHAR ErrorDescription[TTYPE_MAX_ERROR])
{
	 	 AFX_MANAGE_STATE(AfxGetStaticModuleState());

	 	 HRESULT rc = TTYPE_SUCCESS;
	 	 CConnectionContext *pContext=0;

	 	 // lookup the context information for the specified SourceID
	 	 CString sSourceID = SourceID;
	 	 m_ServerConnections.Lookup(sSourceID, (void *&)pContext);

	 	 if (pContext == 0)
	 	 	 return TTYPE_ERROR_INVALID_SOURCEID;

	 	 try
	 	 {
	 	 	 /* CODE OMITTED: Retrieve assets associated with NodeID.
	 	 	 Perform source control UndoCheckOut on assets. */

	 	 }
	 	 catch (_com_error &e)
	 	 {
	 	 	 rc = TTYPE_ERROR;
	 	 	 CString sError = (BSTR) e.Description();
	 	 	 tcscpy(ErrorDescription, (LPCTSTR) sError );
	 	 }
	 	 return rc;
}	 

See Also

TTAddToSourceControl(), TTCheckIn(), TTCheckOut(), TTGetSourceControlStatus()

prevnext


Rational TestManager Extensibility Reference Rational Software Corporation
Copyright (c) 2003, Rational Software Corporation http://www.rational.com
support@rational.com
info@rational.com