wtx.c

vxworks源码源码解读是学习vxworks的最佳途径

 * NOTE: This is a list of WTX protocol calls not accessible from the 
 *       WTX C API and is based on the service numbers in wtxmsg.h
 *
 * WTX_VIO_READ			- not implemented in server (obsolete?)
 * WTX_SYM_TBL_CREATE/DELETE	- to do
 * WTX_SYM_TBL_LIST		- to do
 * WTX_WTX_SERVICE_LIST		- not implemented in server - undefined
 * WTX_WDB_SERVICE_LIST		- not implemented in server - undefined
 * WTX_OBJ_KILL			- (currently TS kill only) Enough ?
 * WTX_OBJ_RESTART		- undefined (obsolete ?)
 */

/*******************************************************************************
*
* wtxToolAttach - connect a WTX client to the target server
*
* This routine establishes a connection to the target server
* called <serverName> and announces the client as a WTX tool called
* <toolName>. If <serverName> does not contain an `@' character, it is
* used as a regular expression; if it matches more than one (registered)
* target server name, an error is returned.  If <serverName> contains 
* an `@' character then it must be an exact match for a valid target 
* server name.
*
* RETURNS: WTX_OK or WTX_ERROR if the attach fails.
*
* ERRORS:
* .iP WTX_ERR_API_ALREADY_CONNECTED 12
* The handle is already connected to a target server.
* .iP WTX_ERR_API_SERVER_NOT_FOUND 
* <serverName> does not match a target server name using the above criteria.
* .iP WTX_ERR_API_AMBIGUOUS_SERVER_NAME 
* <serverName> matches more than one target server name.
* .iP WTX_ERR_SVR_DOESNT_RESPOND
* <serverName> is dead : no RPC connection can be achieved
* .iP WTX_ERR_SVR_IS_DEAD
* <serverName> is dead : server has been found dead
*
* SEE ALSO: WTX_TOOL_ATTACH, wtxToolDetach(), wtxToolConnected(), wtxInfoQ()
*/

STATUS wtxToolAttach 
    (
    HWTX	 hWtx,		/* WTX API handle */
    const char * serverName,	/* Target Server name */
    const char * toolName	/* tool name */
    )
    
    {
    WTX_ERROR_T		callStat;		/* status of WTX call */
    WTX_MSG_TOOL_DESC	in;			/* WTX param */
    WTX_MSG_TOOL_DESC *	pOut;			/* WTX result */
    char *		envUser;		/* result of getenv(USER) */
    char		userName [256];		/* to format "user@host" */
    char		serverAtHost [256];	/* serverName@host */
    char		hostNameBuf [32];	/* for gethostname () */
    WTX_DESC *		pSaveDesc;
    WTX_DESC *		pTsDesc;		/* Info about Target Server */
#ifdef WIN32
    char                usrName [256];		/* holds name for Win32 */
#endif

    WTX_CHECK_HANDLE (hWtx, WTX_ERROR);

    if (wtxToolConnected (hWtx))
	WTX_ERROR_RETURN (hWtx, WTX_ERR_API_ALREADY_CONNECTED, WTX_ERROR);

    if (hWtx->pServerDesc) 
	{
	wtxResultFree (hWtx, hWtx->pServerDesc);
	hWtx->pServerDesc = NULL;
	}

    /* save current name in serverAtHost */

    strcpy (serverAtHost, serverName);

    if (!strchr (serverName, '@'))			/* name: tgtsvr */
	{
	WTX_DESC_Q *	pTsDescQ;	/* Q Info about Target Server */

	pTsDescQ = wtxInfoQ (hWtx, (char *)serverName, "tgtsvr", NULL);

	if (pTsDescQ == NULL)
	    WTX_ERROR_RETURN (hWtx, WTX_ERR_API_SERVER_NOT_FOUND, WTX_ERROR);
	
	if (pTsDescQ->pNext != NULL)
	    {
	    wtxResultFree (hWtx, pTsDescQ);
	    WTX_ERROR_RETURN (hWtx, WTX_ERR_API_AMBIGUOUS_SERVER_NAME, 
			      WTX_ERROR);
	    }

	/*
	 * There is an @ in the target server name, let's see if it is really
	 * in registry data base.
	 */

	strcpy (serverAtHost, pTsDescQ->wpwrName);
	wtxResultFree (hWtx, pTsDescQ);
	}

    pTsDesc = wtxInfo (hWtx, (char *)serverAtHost);	/* name: tgtsvr@host */

    if (pTsDesc == NULL)
	WTX_ERROR_RETURN (hWtx, hWtx->errCode, WTX_ERROR);

    hWtx->pServerDesc = pTsDesc;

    /* allocate space to copy server information */

    if ((pSaveDesc = (WTX_DESC *) malloc (sizeof (WTX_DESC))) == NULL)
	{
	wtxResultFree (hWtx, hWtx->pServerDesc);
	WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
	}

    /* copy server information */

    memcpy ((void *) pSaveDesc, (void *) hWtx->pServerDesc, sizeof (WTX_DESC));

    if (hWtx->pServerDesc->wpwrName != NULL)
	{
	if ((pSaveDesc->wpwrName = (char *) malloc (strlen
			    (hWtx->pServerDesc->wpwrName) + 1)) == NULL)
	    {
	    free (pSaveDesc);
	    wtxResultFree (hWtx, hWtx->pServerDesc);
	    WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
	    }
	    
        strcpy (pSaveDesc->wpwrName, hWtx->pServerDesc->wpwrName);
	}

    if (hWtx->pServerDesc->wpwrKey != NULL)
	{
	if ((pSaveDesc->wpwrKey = (char *) malloc (strlen
			    (hWtx->pServerDesc->wpwrKey) + 1)) == NULL)
	    {
	    free (pSaveDesc);
	    free (pSaveDesc->wpwrName);
	    wtxResultFree (hWtx, hWtx->pServerDesc);
	    WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
	    }
	    
        strcpy (pSaveDesc->wpwrKey, hWtx->pServerDesc->wpwrKey);
	}

    if (hWtx->pServerDesc->wpwrType != NULL)
	{
	if ((pSaveDesc->wpwrType = (char *) malloc (strlen
			    (hWtx->pServerDesc->wpwrType) + 1)) == NULL)
	    {
	    free (pSaveDesc);
	    free (pSaveDesc->wpwrName);
	    free (pSaveDesc->wpwrKey);
	    wtxResultFree (hWtx, hWtx->pServerDesc);
	    WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
	    }
	    
        strcpy (pSaveDesc->wpwrType, hWtx->pServerDesc->wpwrType);
	}

    wtxResultFree (hWtx, hWtx->pServerDesc);
    registryDisconnect (hWtx);

    hWtx->pServerDesc = pSaveDesc;

    if (wtxExchangeInitialize (&hWtx->server) != WTX_OK ||
	wtxExchangeInstall (hWtx->server, 
			    wtxRpcExchangeCreate, 
			    wtxRpcExchangeDelete, 
			    wtxRpcExchange, 
			    wtxRpcExchangeFree, 
			    wtxRpcExchangeControl) != WTX_OK ||
	wtxExchangeCreate (hWtx->server, 
			   hWtx->pServerDesc->wpwrKey) != WTX_OK)
	{
	WTX_ERROR_T errCode;

	/* Record the error code */
	errCode = wtxExchangeErrGet (hWtx->server);

	/* free server descriptor */
	serverDescFree (hWtx);

	/* Cleanup the exchange */
	wtxExchangeTerminate (hWtx->server);
	hWtx->server = NULL;

	WTX_ERROR_RETURN (hWtx, errCode, WTX_ERROR);
	}

    memset (&in, 0, sizeof (in));

    in.wtxToolDesc.toolName = (char *) toolName;
#ifdef HOST
#ifdef WIN32
    {
        UINT32 size = sizeof (usrName);    

        if(!GetUserName (usrName, &size))
	    envUser = NULL;
	else
	    envUser = usrName;
    }
#else
    envUser = getenv ("USER");
#endif /* WIN32 */
    gethostname (hostNameBuf, sizeof (hostNameBuf));
#else
    envUser = sysBootParams.usr;
    strcpy (hostNameBuf, sysBootParams.targetName);
#endif /* HOST */
    if (envUser == NULL)
	envUser = "unknown";
    if (hostNameBuf[0] == '\0')
	strcpy (hostNameBuf, "unknown");
    sprintf (userName, "%.24s@%.24s", envUser, hostNameBuf);

    in.wtxToolDesc.userName = userName;

    pOut = calloc (1, sizeof (WTX_MSG_TOOL_DESC));
    if (pOut == NULL)
	{
	/* Close the connection to the server */
	wtxExchangeDelete (hWtx->server);

	/* free server descriptor */
	serverDescFree (hWtx);

	/* Clean up the exchange */
	wtxExchangeTerminate (hWtx->server);
	hWtx->server = NULL;

	WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
	}

    /* Do the attach call */
    callStat = exchange (hWtx, WTX_TOOL_ATTACH, &in, pOut);
	
    if (callStat != WTX_ERR_NONE)
	{
	/* Close the connection to the server */
	wtxExchangeDelete (hWtx->server);

	/* free server descriptor */
	serverDescFree (hWtx);

	/* Clean up the exchange */
	wtxExchangeTerminate (hWtx->server);
	hWtx->server = NULL;

	WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
	}

    /* Set the msgToolId and pToolDesc filed in the HWTX for future use */
    hWtx->pToolDesc = &pOut->wtxToolDesc;
    hWtx->msgToolId.wtxCore.objId = pOut->wtxToolDesc.id;

    return (WTX_OK);
    }


/*******************************************************************************
*
* wtxToolConnected - check to see if a tool is connected to a target server
*
* This routine checks if the tool represented by <hWtx> is currently
* connected to a target server. 
*
* NOTE: If <hWtx> is an invalid handle then FALSE is returned.
*
* RETURNS: TRUE if the tool is connected, FALSE otherwise.
*
* SEE ALSO: wtxErrClear(), wtxErrGet()
*/

BOOL32 wtxToolConnected 
    (
    HWTX	hWtx	/* WTX API handle */
    )
    {
    WTX_CHECK_HANDLE (hWtx, FALSE);

    return (hWtx->server != NULL);
    }

/*******************************************************************************
*
* wtxToolDetach - detach from the target server
*
* This routine detaches from the target server. 
* The connection status for <hWtx> is cleared and any memory
* allocated by the tool attach is freed. 
*
* NOTE: Even if the detach fails internally (for example, the server
* it is attached to has died), the API still puts the handle into a
* detached state and performs all necessary internal cleanup. In this
* case the internal error is `not' reported since the tool is no longer
* attached and the handle can subsequently be attached to another server.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: WTX_TOOL_DETACH, wtxToolAttach()
*/

STATUS wtxToolDetach 
    (
    HWTX	hWtx		/* WTX API handle */
    )
    {
    WTX_ERROR_T		callStat;	/* WTX call status */
    WTX_MSG_RESULT	out;		/* WTX result */

    WTX_CHECK_HANDLE (hWtx, WTX_ERROR);

    if (! wtxToolConnected(hWtx))
	return (WTX_OK);

    memset (&out, 0, sizeof (out));

    callStat = exchange (hWtx, WTX_TOOL_DETACH, &hWtx->msgToolId, &out);

    /* Free allocated memory and close neatly the connection to the server */

    wtxExchangeFree (hWtx->server, WTX_TOOL_DETACH, &out);

    /* 
     * free the server descriptor and the strings that were allocated in 
     * wtxToolAttach().
     */

    serverDescFree (hWtx);

    toolCleanup(hWtx);

    /* Actively ignore any errors that may occur */

    return (WTX_OK);
    }


/*******************************************************************************
*
* wtxInitialize - initialization routine to be called by the WTX client
*
* This routine allocates a handle structure for the tool's use and
* does any initialization required for use of the WTX interface.  All
* subsequent calls by the tool should use the handle returned in <phWtx>.
* If WTX_ERROR is returned and the handle <phWtx> is zero, then the
* initialization failed because the internal handle structure could
* not be allocated. Otherwise use wtxErrMsgGet() to find the cause
* of the error.
* 
* RETURNS: WTX_OK or WTX_ERROR if the initialization fails.
*
* ERRORS: 
* .iP WTX_ERR_API_INVALID_ARG 12
* The pointer <phWtx> is NULL.
* .iP WTX_ERR_API_MEMALLOC 
* The handle cannot be allocated.
*
* SEE ALSO: wtxTerminate(), wtxVerify()
*/

STATUS wtxInitialize 
    (
    HWTX * phWtx	/* RETURN: handle to use in subsequent API calls */
    )
    {
    if (phWtx == NULL)
	WTX_ERROR_RETURN (NULL, WTX_ERR_API_INVALID_ARG, WTX_ERROR);

    *phWtx = calloc (1, sizeof (struct _wtx));
    
    if (*phWtx == NULL)
	WTX_ERROR_RETURN (NULL, WTX_ERR_API_MEMALLOC, WTX_ERROR);
    
    /* Set the field that identifies this as a valid handle */
    (*phWtx)->self = *phWtx;

    return (WTX_OK);
    }


/*******************************************************************************
*
* wtxTerminate - terminate the use of a WTX client handle
*
* This routine destroys the specified context handle so it may no
* longer be used in WTX API calls.  If the tool is attached to a
* target server, it is first detached. (It is forcibly detached if
* errors make a normal detach impossible.)  Any memory allocated by 
* the handle is freed and the handle is invalidated; any subsequent 
* use causes an abort.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: wtxInitialize(), wtxVerify()
*/

STATUS wtxTerminate
    (
    HWTX	hWtx		/* WTX API handle */
    )
    {
    WTX_CHECK_HANDLE (hWtx, WTX_ERROR);


    if (wtxToolConnected (hWtx))
	wtxToolDetach (hWtx);

    if (hWtx->pServerDesc) 
	wtxResultFree (hWtx, hWtx->pServerDesc);

    if (hWtx->pSelfDesc)
	wtxResultFree (hWtx, hWtx->pSelfDesc);

    if (hWtx->registry)
	wtxExchangeDelete (hWtx->registry);

    wtxExchangeTerminate (hWtx->server);
    wtxExchangeTerminate (hWtx->registry);

    /* Invalidate this handle in case it is used after terminate */