wtx.c

VXWORKS源代码

    )

    {
    WTX_CHECK_HANDLE (hWtx, WTX_ERROR);

    return (hWtx->errCode);
    }

/*******************************************************************************
*
* wtxErrHandlerAdd - add an error handler for the WTX handle
*
* This routine adds a new error handler to the list of registered handlers
* for the handle <hWtx>.  The last error handler added is the first one
* called when an error occurs. The function <pFunc> is called with three
* arguments, the handle on which the error occurred, the client data
* <pClientData>, and a call data parameter which is the error code. If the
* function returns the value TRUE then each previously registered handler
* function is called in turn until all are called or one returns the
* value FALSE.
*
* EXAMPLE
* The following is a sample error handler:
*
* .CS
*   BOOL32 errorHandler
*       (
*	HWTX   hWtx,	     /@ WTX API handle @/
*	void * pClientData,  /@ client data from wtxErrHandlerAdd() call @/
*	void * errCode       /@ error code passed from wtxErrDispatch() @/
*       )
*
*       {
*	/@ print an error message @/
*	
*	fprintf (stderr, 
*		 "Error %s (%d) from server %s\n", 
*		 wtxErrMsgGet (hWtx),
*		 (WTX_ERROR_T) errCode,		/@ or use wtxErrGet() @/
*		 wtxTsNameGet (hWtx));
*
*	/@ return TRUE allowing previously installed handlers to be called @/
*
*	return TRUE;
*	}
* .CE
*
* RETURNS: A new handler ID or NULL on failure.
*
* ERRORS:
* .iP WTX_ERR_API_MEMALLOC 12
* No memory is available to add the new handler.
*
* SEE ALSO: wtxErrHandlerRemove(), wtxErrDispatch()
*/

WTX_HANDLER_T wtxErrHandlerAdd 
    (
    HWTX		hWtx,		/* WTX API handle */
    WTX_HANDLER_FUNC	pFunc,		/* function to call on error */
    void *		pClientData	/* data to pass function */
    )
    {
    WTX_HANDLER_T descNew;

    WTX_CHECK_HANDLE (hWtx, NULL);

    descNew = calloc (1, sizeof (_WTX_HANDLER_T));

    if (descNew == NULL)
	WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, NULL);
    
    descNew->pFunc = pFunc;
    descNew->pClientData = pClientData;
    descNew->prev = hWtx->errHandler;
    hWtx->errHandler = descNew;

    return descNew;
    }

/*******************************************************************************
*
* wtxErrHandlerRemove - remove an error handler from the WTX handle
*
* This function removes the error handler referenced by <errHandler> from 
* the handler list for <hWtx>. The error handler ID <errHandler> must be a 
* valid error handler ID returned by a call of wtxErrHandlerAdd().
*
* NOTE: It is safe for wtxErrHandlerRemove() to be called from within an
* error handler function, even if the call is to remove itself.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* ERRORS:
* .iP WTX_ERR_API_HANDLER_NOT_FOUND 12
* <errHandler> is not a valid handler ID.
*
* SEE ALSO: wtxErrHandlerAdd(), wtxErrDispatch() 
*/

STATUS wtxErrHandlerRemove 
    (
    HWTX hWtx,			/* WTX API handle */
    WTX_HANDLER_T errHandler	/* Error handler to remove */
    )
    {
    WTX_HANDLER_T desc;
    WTX_HANDLER_T last;

    WTX_CHECK_HANDLE (hWtx, WTX_ERROR);

    last = NULL;

    for (desc = hWtx->errHandler; desc; desc = desc->prev)
	{
	if (desc == errHandler)
	    {
	    /* Got the one to remove */
	    if (last)
		last->prev = desc->prev;
	    else
		hWtx->errHandler = desc->prev;
	    free (desc);
	    return (WTX_OK);
	    }
	last = desc;
	}

    WTX_ERROR_RETURN (hWtx, WTX_ERR_API_HANDLER_NOT_FOUND, WTX_ERROR);
    }

/*******************************************************************************
*
* wtxErrDispatch - dispatch an error with supplied code for the given handle
*
* This function records the error <errCode> against the handle <hWtx> and 
* calls all the registered error handlers for it until one returns FALSE.
*
* RETURNS: WTX_OK or WTX_ERROR if the handle is invalid.
*
* SEE ALSO: wtxErrHandlerAdd()
*/

STATUS wtxErrDispatch
    (
    HWTX	hWtx,		/* WTX API handle */
    WTX_ERROR_T	errCode		/* error code to register */
    )
    {
    WTX_HANDLER_T desc;
    BOOL32 continueToDispatch;

    /* cannot use macro here as it will cause recursion via WTX_ERROR_RETURN */

    if (hWtx == NULL || hWtx->self != hWtx)
	{
	/* cannot do anything with the error */

	/* FIXME: should implement a global error handler */
	return WTX_ERROR;
	}

    /* Record the error code */
    hWtx->errCode = errCode;
    hWtx->errMsg = NULL;

    continueToDispatch = TRUE;
    desc = hWtx->errHandler; 

    /* Dispatch the error to all the error handlers */
    while ((desc != NULL) && continueToDispatch)
	{
	WTX_HANDLER_T prev;

	/* Just in case the handler removes itself! */
	prev = desc->prev;

	/* Be sure the function is non-null */
	if (desc->pFunc)
	    continueToDispatch = desc->pFunc (hWtx, 
					      desc->pClientData, 
					      (void *) errCode);
	desc = prev;
	}

    return (WTX_OK);
    }

/*******************************************************************************
* 
* wtxErrMsgGet - fetch the last network WTX API error string
*
* This routine gets a meaningful string for the last WTX API call
* that returned WTX_ERROR. The string is only valid after a WTX
* call has returned an error.
*
* NOTE: The return value is a pointer to internal data and must
* not be freed by the caller. Also the string is only valid until
* the next error occurs or wtxErrClear() is called. It must
* be copied by the caller if the value must be stored.
*
* RETURNS: A pointer to a string or NULL if an error has occurred. 
*
* SEE ALSO: wtxErrClear(), wtxErrGet()
*/

const char * wtxErrMsgGet
    (
    HWTX	hWtx	/* WTX API handle */
    )
    {
    WTX_CHECK_HANDLE (hWtx, NULL);

    /* This allows for caching of previous values but is not yet implemented */
    if (hWtx->errMsg != NULL)
	return hWtx->errMsg;
    else
	{
	hWtx->errMsg = wtxErrToMsg (hWtx, hWtx->errCode);
	return hWtx->errMsg;
	}
    }


/*******************************************************************************
*
* wtxErrToMsg - convert an WTX error code to a descriptive string
*
* This routine takes an error code which has been returned by a WTX API
* call and returns a descriptive string. The value returned is a pointer
* to a string in statically allocated memory. The string must be copied 
* if the value is to be stored and it must not be freed by the caller.
*
* RETURNS: A pointer to an error string.
*/

const char * wtxErrToMsg
    (
    HWTX hWtx, 
    WTX_ERROR_T errCode
    )
    {
    static char buffer [256];

    if (errCode == WTX_ERR_NONE)
	return "No error";

    if ((errCode > WTXERR_BASE_NUM) && (errCode < WTX_ERR_LAST))
	{
	FILE * fp;

#ifdef WIN32
	sprintf (buffer, "%s\\host\\resource\\tcl\\wtxerrdb.tcl", 
		 getenv ("WIND_BASE"));
#else
	sprintf (buffer, "%s/host/resource/tcl/wtxerrdb.tcl", 
		 getenv ("WIND_BASE"));
#endif
    
	fp = fopen (buffer, "r");
	while (fp != NULL && ! ferror (fp))
	    {
	    UINT32	errNum;
	    char	errStr[256];

	    if (fgets (buffer, sizeof (buffer), fp) == NULL)
		break;

	    if (sscanf (buffer, "set wtxError(0x%x) %s", &errNum, errStr) == 2
		&& (errNum == (UINT32)errCode))
		{
		sprintf (buffer, "%s", errStr);
		fclose (fp);
		return buffer;
		}
	    }

	if (fp)
	    fclose (fp);

	/* A WTX error we have no error text for */
	sprintf (buffer, "WTX error %#x", errCode);
	}

#ifdef SUN4_SUNOS4
    /*
     * Avoid strerror() on SUNOS4, as this will pull libiberty.a into
     * the link, making it more difficult to bind this code into a
     * shared library.
     */
    else if (errCode > 0 && errCode < sys_nerr && sys_errlist [errCode] != NULL)
        {
        /* Probably a system error */
        sprintf (buffer, "%s (%d)", sys_errlist [errCode], errCode);
        }
#else  /* !SUN4_SUNOS4 */
    else if (strerror (errCode) != NULL)
        /* Probably a system error */
        sprintf (buffer, "%s (%d)", strerror (errCode), errCode);
#endif /* SUN4_SUNOS4 */

    else
	/* Some other error we don't know about */
	sprintf (buffer, "error %d (%#x)", errCode, errCode);

    return buffer;
    }

/*******************************************************************************
*
* wtxErrClear - explicitly clear any error status for the tool
*
* This routine clears an error message already recorded. It can be
* called before a WTX routine if you want to test for an error afterwards
* by checking whether wtxErrGet() returns a non-zero value.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: wtxErrGet(), wtxErrMsgGet(), wtxErrSet()
*/

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

    hWtx->errCode = WTX_ERR_NONE;
    hWtx->errMsg = NULL;

    return (WTX_OK);
    }


/*******************************************************************************
*
* wtxErrExceptionFunc - a function to handle an error using longjmp()
*
* This function is called as part of the error handling process shown in the
* discussion of C++ style exception catching in the wtx library description
* (\f2WTX C Library\fP).  The WTX_TRY macro, which registers the error
* handler wtxErrExceptionFunc(), is found in wtx.h.  <pClientData> contains
* the address of <jumpBuf> from WTX_TRY and <pCallData> is the error code 
* that is returned by WTX_TRY and should be cast to the type WTX_ERROR_T..
*
* RETURNS: FALSE if <pClientData> is NULL, otherwise it does not return.
* It executes a longjmp() back to <jumpBuf> in the WTX_TRY macro, which
* returns the error code passed back by <pCallData>.
*
* SEE ALSO: wtxErrHandlerAdd(), wtxErrDispatch()
*/

BOOL32 wtxErrExceptionFunc 
    (
    HWTX hWtx,			/* WTX API handle */
    void * pClientData,		/* pointer to a jump buffer */
    void * pCallData		/* error code to return via setjmp() */
    )
    {
    if (pClientData != NULL)
	longjmp (pClientData, (int) pCallData);

    return FALSE;
    }


/*******************************************************************************
*
* wtxClientDataGet - get the client data associated with the WTX handle
*
* This routine sets the pointer pointed at by <ppClientData> to the
* value set by the last call to wtxClientDataSet() for the handle <hWtx>.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* ERRORS: 
* .iP WTX_ERR_API_INVALID_ARG 12
* <ppClientData> is NULL.
*
* SEE ALSO: wtxClientDataSet()
*/

STATUS wtxClientDataGet 
    (
    HWTX hWtx,			/* WTX API handle */
    void ** ppClientData	/* RETURN: pointer to client data pointer */
    )
    {
    WTX_CHECK_HANDLE (hWtx, WTX_ERROR);

    if (ppClientData == NULL)
	WTX_ERROR_RETURN (hWtx, WTX_ERR_API_INVALID_ARG, WTX_ERROR);

    *ppClientData = hWtx->pClientData;

    return (WTX_OK);
    }


/*******************************************************************************
*
* wtxClientDataSet - set the client data associated with the WTX handle
*
* This routine causes the value <pClientData> to be associated with the
* WTX API handle <hWtx>. The client data can be used by the
* caller in any way and, except when in the set and get routines,
* is not used or altered in any way by the WTX API. The initial value
* of the client data before it is set is always NULL.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: wtxClientDataGet().
*/

STATUS wtxClientDataSet 
    (
    HWTX hWtx,			/* WTX API handle */
    void * pClientData		/* value to associate with handle */
    )
    {
    WTX_CHECK_HANDLE (hWtx, WTX_ERROR);
    hWtx->pClientData = pClientData;

    return (WTX_OK);
    }

/*******************************************************************************
*
* wtxAgentModeGet - get the mode of the target agent