Functions
_UVSC_FUNC_ void	UVSC_Version (UINT pUVSCVersion, UINT pUVSOCKVersion)

_UVSC_FUNC_ UVSC_STATUS	UVSC_Init (int uvMinPort, int uvMaxPort)

_UVSC_FUNC_ UVSC_STATUS	UVSC_UnInit (void)

_UVSC_FUNC_ UVSC_STATUS	UVSC_OpenConnection (char name, int iConnHandle, int pPort, char uvCmd, UVSC_RUNMODE uvRunmode, uvsc_cb callback, void cb_custom, char logFileName, xBOOL logFileAppend, log_cb logCallback)

_UVSC_FUNC_ UVSC_STATUS	UVSC_CloseConnection (int iConnHandle, xBOOL terminate)

_UVSC_FUNC_ UVSC_STATUS	UVSC_ConnHandleFromConnName (char name, int iConnHandle)

_UVSC_FUNC_ UVSC_STATUS	UVSC_GetLastError (int iConnHandle, UV_OPERATION msgType, UV_STATUS status, char *str, int maxStrLen)

_UVSC_FUNC_ UVSC_STATUS	UVSC_LogControl (int iConnHandle, xBOOL enableRaw, xBOOL enableTrace)

Description

Function Documentation

_UVSC_FUNC_ UVSC_STATUS UVSC_CloseConnection	(	int	iConnHandle,
		xBOOL	terminate
	)

Close a connection to a uVision session

Parameters

iConnHandle	Handle for the connection, as returned by UVSC_OpenConnection
terminate	Pass 'xTRUE' to terminate uVision. This parameter is ignored and the session is automatically terminated if it was auto-started

Returns: UVSC_STATUS_SUCCESS on success, or an error code

This function closes a connection to a uVision session. If the session was auto-started it is automatically terminated. If it was not auto-started, it can be terminated, or left running.

_UVSC_FUNC_ UVSC_STATUS UVSC_ConnHandleFromConnName	(	char *	name,
		int *	iConnHandle
	)

Get a connection handle (iConnHandle) from a connection name

Parameters

name	Pointer to a zero terminated string containing a unique connection name. The name should correspond to a name that was previously passed to UVSC_OpenConnection. This pointer must not be NULL
iConnHandle	Pointer to a variable to contain the handle assigned to this connection. The value assigned will be invalid if the function returns an error. This pointer must not be NULL

Returns: UVSC_STATUS_SUCCESS on success, or an error code

Precondition: UVSC_OpenConnection must have been called successfully

Use this function to convert a connection name to a connection handle (iConnHandle) to be used with other UVSC API functions.

_UVSC_FUNC_ UVSC_STATUS UVSC_GetLastError	(	int	iConnHandle,
		UV_OPERATION *	msgType,
		UV_STATUS *	status,
		char *	str,
		int	maxStrLen
	)

Retreive detailed information on the last UVSOCK error.

Parameters

iConnHandle	Handle for the connection, as returned by UVSC_OpenConnection
msgType	Pointer to a variable to contain the UVSOCK message that caused the error
status	Pointer to a variable to contain status code of the UVSOCK message that caused the error
str	Pointer to a buffer to contain the zero terminated error string of the UVSOCK message that caused the error
maxStrLen	Size of the buffer pointer to by str (bytes)

Returns: UVSC_STATUS_SUCCESS on success, or an error code

Precondition: UVSC_OpenConnection must have been called successfully; The last call to UVSC_XXXX should have returned an error

Use this function to get extended error information when a UVSC command function (eg UVSC_DBG_CALC_EXPRESSION) fails. It is thread-safe and returns the last error for the calling thread, not the last error for the entire connection, so should be called from the same thread as the UVSC command function that caused the error.

_UVSC_FUNC_ UVSC_STATUS UVSC_Init	(	int	uvMinPort,
		int	uvMaxPort
	)

Initialize UVSC

Parameters

uvMinPort	Minimum port avialable to the automatic port allocator. This must not be smaller than UVSC_MIN_AUTO_PORT
uvMaxPort	Maximum port avialable to the automatic port allocator. This must not be larger than UVSC_MAX_AUTO_PORT

Initialize UVSC with this function, which must be called prior to any other UVSC function, except UVSC_Version. The function also verifies whether the port range (uvMaxPort - uvMinPort) can handle the maximum defined client connections (UVSC_MAX_CLIENTS).

(uvMaxPort - uvMinPort) < UVSC_MAX_CLIENTS)

See Also

_UVSC_FUNC_ UVSC_STATUS UVSC_LogControl	(	int	iConnHandle,
		xBOOL	enableRaw,
		xBOOL	enableTrace
	)

Control message logging

Parameters

iConnHandle	Handle for the connection, as returned by UVSC_OpenConnection
enableRaw	Pass 'xTRUE' to enable logging of raw UVSOCK data, or 'xFALSE' to disable it. The default option on connection is 'xFALSE'
enableTrace	Pass 'xTRUE' to enable logging of UVSC function trace, or 'xFALSE' to disable it. The default option on connection is 'xTRUE'

Returns: UVSC_STATUS_SUCCESS on success, or an error code

Precondition: UVSC_OpenConnection must have been called successfully; Logging should be enabled for this connection handle (ie one or both of logFileName and logCallback passed to UVSC_OpenConnection should not be NULL)

Use this function to control what information is logged via the log file or logging callback.

_UVSC_FUNC_ UVSC_STATUS UVSC_OpenConnection	(	char *	name,
		int *	iConnHandle,
		int *	pPort,
		char *	uvCmd,
		UVSC_RUNMODE	uvRunmode,
		uvsc_cb	callback,
		void *	cb_custom,
		char *	logFileName,
		xBOOL	logFileAppend,
		log_cb	logCallback
	)

Open a connection to uVision session

Parameters

name	Pointer to a zero terminated string containing a unique connection name. This name can be used later to retrieve the connection handle (iConnHandle) via the UVSC_ConnHandleFromConnName function. If a connection name is not required this parameter should be NULL
iConnHandle	Pointer to a variable to contain the handle assigned to this connection. The value assigned will be invalid if the function returns an error. This pointer must not be NULL
pPort	Pointer to a variable containing the port of an existing uVision session to connect, or the value UVSC_PORT_AUTO to auto-start a uVision session for this connection. If the function returns successfully, this variable will contain the port that was used for the connection. This pointer must not be NULL.
uvCmd	Pointer to a zero terminated string containing the path to a uVision executable to be started automatically for this connection. If uVision is not being auto-started this parameter is ignored and should be NULL
uvRunmode	Indicates the mode uVision should be started in when auto-started. If uVision is not being auto-started this parameter is ignored
callback	Pointer to a function to receive callbacks from UVSC. The callbacks provide notification of asynchronous UVSOCK messages, connection events, and errors relating to the connection. NOTE: UVSC_xxx API functions must not be called from the callback. To call a UVSC_xxx function in response to the callback, a notification must be passed another thread, which can then call the UVSC_xxx function.
cb_custom	This pointer will be returned in the calls to the callback function. It may be used for any purpose, but a common usage is for keeping track of the 'this' pointer of a C++ object relating to the connection
logFileName	Pointer to a zero terminated string containing the path to a file to use for logging UVSOCK messages for this connection for debug purposes. If a debugging log file is not required, this parameter should be NULL
logFileAppend	Pass 'xTRUE' to append to the log file specified in logFileName, or 'xFALSE' to overwrite the file. If logFileName is NULL, this parameter is ignored
logCallback	Pointer to a function to receive logging callbacks. These callbacks contain the same information that is entered into the log file. If this callback is not required, this parameter should be NULL

Returns: UVSC_STATUS_SUCCESS on success, or an error code

Precondition: UVSC_Init must have been called successfully

This function opens a connection to a uVision session. The session can be either an existing session, or UVSC can automatically start a new session.

To auto-start a new uVision session (recommended):

pPort must be UVSC_PORT_AUTO
uvCmd must be the path to a valid uVision executable that supports UVSOCK

Auto-starting uVision has the following advantages:

uVision is in a known state from the beginning of the connection
uVision can be started in a special mode, that restricts how a user can interact with the remotely controlled session
If the uVision session is terminated by an application other than UVSC, UVSC automatically restarts the uVision session
uVision starts hidden from the user, and can remain that way for the whole session, operating silently in the background, if necessary
The uVision session is a sub-process of UVSC, and can therefore be reliably terminated by UVSC when the connection is closed

To connect to an exisiting uVision session (not recommended):

pPort must be the UVSOCK port number of the existing uVision session
uvCmd must be NULL

_UVSC_FUNC_ UVSC_STATUS UVSC_UnInit ( void )

Uninitialize UVSC

Precondition: UVSC_Init should have been called successfully

Call this function to uninitialize UVSC. This function should be called before the UVSC library is unloaded from memory. All connected sessions will be automatically disconnected.

_UVSC_FUNC_ void UVSC_Version	(	UINT *	pUVSCVersion,
		UINT *	pUVSOCKVersion
	)

Get the library and interface versions

Parameters

pUVSCVersion	Pointer to a variable to contain the UVSC library version
pUVSOCKVersion	Pointer to a variable to contain the UVSOCK interface version

Returns the UVSC library and UVSOCK interface versions for this library.

The UINT version is converted to an X.YY version number by the following formula:

 X.YY = UV3_SOCKIF_VERS / 100

For example:

 *pUVSOCKVersion = 201 ==> V2.01

This function can be used before initializing the interface with UVSC_Init.

Functions

Description

Function Documentation