Using the µVision Socket Interface: Connection Control Functions

| Using the µVision Socket Interface Application Note 198 Control and monitor µVision via the built-in TCP/IP interface

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Functions
Connection Control Functions
Client Functions

## 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_OpenConnection
  - UVSC_PORT_AUTO

_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.