Using the µVision Socket Interface: Project 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
Project Functions
Client Functions

## Functions
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_LOAD (int iConnHandle, PRJDATA *pProjectFile, int projectFileLen)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_CLOSE (int iConnHandle)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_ADD_FILE (int iConnHandle, PRJDATA *pGroupFiles, int groupFilesLen)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_DEL_FILE (int iConnHandle, PRJDATA *pGroupFiles, int groupFilesLen)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_ENUM_FILES (int iConnHandle, SSTR *pGroup, int groupLen, SSTR *pFiles, int *pFileIndexes, int *pFileCount)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_ADD_GROUP (int iConnHandle, PRJDATA *pGroups, int groupsLen)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_DEL_GROUP (int iConnHandle, PRJDATA *pGroups, int groupsLen)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_SET_TARGET (int iConnHandle, PRJDATA *pTargets, int targetsLen)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_SET_OUTPUTNAME (int iConnHandle, PRJDATA *pTargets, int targetsLen)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_ENUM_GROUPS (int iConnHandle, SSTR *pGroups, int *pGroupIndexes, int *pGroupCount)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_ENUM_TARGETS (int iConnHandle, SSTR *pTargets, int *pTargetIndexes, int *pTargetCount)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_ACTIVE_FILES (int iConnHandle, UINT *pActiveFileCount)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_BUILD (int iConnHandle, xBOOL rebuild)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_BUILD_CANCEL (int iConnHandle)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_CLEAN (int iConnHandle)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_FLASH_DOWNLOAD (int iConnHandle)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_GET_OPTITEM (int iConnHandle, TRNOPT *pTrnOpt, int trnOptLen)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_SET_OPTITEM (int iConnHandle, TRNOPT *pTrnOpt, int trnOptLen)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_GET_DEBUG_TARGET (int iConnHandle, DBGTGTOPT *pDbgTgtOpt)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_SET_DEBUG_TARGET (int iConnHandle, DBGTGTOPT *pDbgTgtOpt)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_CMD_PROGRESS (int iConnHandle, PGRESS *pPgress, int pgressLen)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_GET_OUTPUTNAME (int iConnHandle, iPATHREQ *piPathRq, SSTR *pName, int nameLen)
_UVSC_FUNC_ UVSC_STATUS | UVSC_PRJ_GET_CUR_TARGET (int iConnHandle, iPATHREQ *piPathRq, SSTR *pName, int nameLen)

## Description

## Function Documentation

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_ACTIVE_FILES | ( | int | iConnHandle,
|  | UINT * | pActiveFileCount
| ) |  |

Get the number of active files in the current project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pActiveFileCount | Pointer to a variable to contain the active file count

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid project is loaded, and uVision is not building, downloading, or debugging

Use this function to get the number of active files in the current project. This is the number of files that will be compiled or assembled when a rebuild is performed.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_ADD_FILE | ( | int | iConnHandle,
|  | PRJDATA * | pGroupFiles,
|  | int | groupFilesLen
| ) |  |

Add a file to a group within the current uVision project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pGroupFiles | Pointer to a structure containing the group name, and filename(s) for the files to add to the group. This is a variable length structure
  groupFilesLen | Size of the pGroupFiles data (bytes)

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid, writable project is loaded, and uVision is not building, downloading, or debugging

Use this function to add a file to a group within the current uVision project.

This is the equivalent of clicking the 'Add Files to Group 'x'' group context menu item in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_ADD_GROUP | ( | int | iConnHandle,
|  | PRJDATA * | pGroups,
|  | int | groupsLen
| ) |  |

Add a group to the current uVision project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pGroups | Pointer to a structure containing the group name(s) for the groups to add to the uVision project. This is a variable length structure
  groupsLen | Size of the pGroupFiles data (bytes)

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid, writable project is loaded, and uVision is not building, downloading, or debugging

Use this function to add a group to the current uVision project.

This is the equivalent of clicking the 'New Group' Project context menu item in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_BUILD | ( | int | iConnHandle,
|  | xBOOL | rebuild
| ) |  |

Build the current uVision project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  rebuild | 'xTRUE':= a rebuild is performed, 'xFALSE':= a build is performed

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid project is loaded, and uVision is not building, downloading, or debugging

Use this function to build or rebuild the current uVision project.

This is the equivalent of clicking the 'Project–>Build', or 'Project–>Rebuild all target files' menu item in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_BUILD_CANCEL | ( | int | iConnHandle | ) |

Cancel a build that is currently in progress

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A project build is in progress

Use this function to cancel a build that is currently in progress. In the case of cancelling a UVSC initiated build, it must be called from a different thread than the UVSC_PRJ_BUILD function, because the build function will not return until the build is complete.

This is the equivalent of clicking the 'Project–>Stop Build' menu item in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_CLEAN | ( | int | iConnHandle | ) |

Clean the current uVision project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid project is loaded, and uVision is not building, downloading, or debugging

Use this function to clean the current uVision project.

This is the equivalent of clicking the 'Project–>Clean target' menu item in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_CLOSE | ( | int | iConnHandle | ) |

Close the current uVision project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid project is loaded, and uVision is not building, downloading, or debugging

Use this function to close the current uVision project, saving all the project and files.

This is the equivalent of clicking the 'Project–>Close Project' menu item in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_CMD_PROGRESS | ( | int | iConnHandle,
|  | PGRESS * | pPgress,
|  | int | pgressLen
| ) |  |

Control the uVision UI progress bar

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pPgress | Pointer to a structure containing the progress bar data set. This is a variable length structure
  pgressLen | Size of the pPgress data (bytes)

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully

Use this function to control the uVision UI progress bar. This can be useful to display a progress bar relating to time consuming client operations via the uVision progress bar.

This is the equivalent of reading settings in the 'Options for XYZ' dialogs in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_DEL_FILE | ( | int | iConnHandle,
|  | PRJDATA * | pGroupFiles,
|  | int | groupFilesLen
| ) |  |

Remove a file from a group within the current uVision project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pGroupFiles | Pointer to a structure containing the group name, and filename(s) for the files to remove from the group. This is a variable length structure
  groupFilesLen | Size of the pGroupFiles data (bytes)

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid, writable project is loaded, and uVision is not building, downloading, or debugging

Use this function to remove a file from a group within the current uVision project.

This is the equivalent of clicking the 'Remove File 'x'' file context menu item in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_DEL_GROUP | ( | int | iConnHandle,
|  | PRJDATA * | pGroups,
|  | int | groupsLen
| ) |  |

Remove a group from the current uVision project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pGroups | Pointer to a structure containing the group name(s) for the groups to remove from the uVision project. This is a variable length structure
  groupsLen | Size of the pGroupFiles data (bytes)

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid, writable project is loaded, and uVision is not building, downloading, or debugging

Use this function to remove a group from the current uVision project.

This is the equivalent of clicking the 'Remove Group 'x' and its Files' group context menu item in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_ENUM_FILES | ( | int | iConnHandle,
|  | SSTR * | pGroup,
|  | int | groupLen,
|  | SSTR * | pFiles,
|  | int * | pFileIndexes,
|  | int * | pFileCount
| ) |  |

Enumerate the files within a project group

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pGroup | Pointer to a structure containing the group for which to enumerate the files
  groupLen | Length of the pGroup data
  pFiles | Pointer to a structure to contain the file(s)
  pFileIndexes | Pointer to a variable to contain the file index(es) within the pFiles data.
  pFileCount | Pointer to a variable to containing the number of items it is possible to fit into the pFiles and pFileIndexes structures. This variable will be updated with the actual number of files returned.

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid project is loaded, and uVision is not building, downloading, or debugging

Use this function to get a list of all the files that exist within the specified group.

The pointers pFiles and pFileIndexes must point to memory which is a multiple of the size of these structures. This multiple must be passed in the variable pFileCount. The multiple must make the pFiles memory space large enough to contain the maximum number of files that may be returned. If the memory area is not large enough for the returned data, the function will return an error. A recommended value is 256.

The SSTR structure is designed to contain variable length data, therefore it may be the case that one record within pFiles actually takes up more than 1 index. Because of this, the returned data should be interpreted in the following way:

    for (i=0; i<*pFileCount; i++) {
      pointer_to_ith_file = pFiles[pFileIndexes[i]];
    }

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_ENUM_GROUPS | ( | int | iConnHandle,
|  | SSTR * | pGroups,
|  | int * | pGroupIndexes,
|  | int * | pGroupCount
| ) |  |

Enumerate the groups within the current project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pGroups | Pointer to a structure to contain the group(s)
  pGroupIndexes | Pointer to a variable to contain the group index(es) within the pGroups data.
  pGroupCount | Pointer to a variable to containing the number of items it is possible to fit into the pGroups and pGroupIndexes structures. This variable will be updated with the actual number of groups returned.

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid project is loaded, and uVision is not building, downloading, or debugging

Use this function to get a list of all the groups that exist within the current project.

The pointers pGroups and pGroupIndexes must point to memory which is a multiple of the size of these structures. This multiple must be passed in the variable pGroupCount. The multiple must make the pGroups memory space large enough to contain the maximum number of groups that may be returned. If the memory area is not large enough for the returned data, the function will return an error. A recommended value is 256.

The SSTR structure is designed to contain variable length data, therefore it may be the case that one record within pGroups actually takes up more than 1 index. Because of this, the returned data should be interpreted in the following way:

    for (i=0; i<*pGroupCount; i++) {
      pointer_to_ith_group = pGroups[pGroupIndexes[i]];
    }

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_ENUM_TARGETS | ( | int | iConnHandle,
|  | SSTR * | pTargets,
|  | int * | pTargetIndexes,
|  | int * | pTargetCount
| ) |  |

Enumerate the targets within the current project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pTargets | Pointer to a structure to contain the target(s)
  pTargetIndexes | Pointer to a variable to contain the target index(es) within the pTarget data.
  pTargetCount | Pointer to a variable to containing the number of items it is possible to fit into the pTargets and pTargetIndexes structures. This variable will be updated with the actual number of targets returned.

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid project is loaded, and uVision is not building, downloading, or debugging

Use this function to get a list of all the targets that exist within the current project.

The pointers pTargets and pTargetIndexes must point to memory which is a multiple of the size of these structures. This multiple must be passed in the variable pTargetCount. The multiple must make the pTargets memory space large enough to contain the maximum number of target that may be returned. If the memory area is not large enough for the returned data, the function will return an error. A recommended value is 256.

The SSTR structure is designed to contain variable length data, therefore it may be the case that one record within pGroups actually takes up more than 1 index. Because of this, the returned data should be interpreted in the following way:

    for (i=0; i<*pTargetCount; i++) {
      pointer_to_ith_target = pTargets[pTargetIndexes[i]];
    }

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_FLASH_DOWNLOAD | ( | int | iConnHandle | ) |

Download the currently built executable to FLASH

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid project is loaded, has been built successfully, and uVision is not building, downloading, or debugging

Use this function to download the currently built executable to FLASH.

This is the equivalent of clicking the 'Flash–>Download' menu item in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_GET_CUR_TARGET | ( | int | iConnHandle,
|  | iPATHREQ * | piPathRq,
|  | SSTR * | pName,
|  | int | nameLen
| ) |  |

Get the current active target name for the current project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  piPathRq | Pointer to a structure containing the options (Set to 0 for now, unused)
  pName | Pointer to a structure to containing the current active target name
  nameLen | Length of the pName data

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid, writable project is loaded, and uVision is not building, downloading, or debugging

The SSTR structure is designed to contain variable length data, therefore it may be the case that the record within piPathRq actually takes up more than the static structure size.

Use this function to retrieve the current active target name in uVision

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_GET_DEBUG_TARGET | ( | int | iConnHandle,
|  | DBGTGTOPT * | pDbgTgtOpt
| ) |  |

Set the debug uVision target configuration

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pDbgTgtOpt | Pointer to a structure to contain the debug target configuration

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid project is loaded

Use this function to get the debug uVision target configuration

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_GET_OPTITEM | ( | int | iConnHandle,
|  | TRNOPT * | pTrnOpt,
|  | int | trnOptLen
| ) |  |

Get a uVision project option

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pTrnOpt | Pointer to a structure containing the option item to get. The structure will be updated with the option item value. This is a variable length structure, and must be large enough to contain the returned data, otherwise an error code will be returned from the function, see OPT_LMISC
  trnOptLen | Size of the pTrnOpt data (bytes)

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid project is loaded, and uVision is not building, downloading, or debugging

Use this function to get the value of a uVision project option.

This is the equivalent of modifying settings in the 'Options for XYZ' dialogs in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_GET_OUTPUTNAME | ( | int | iConnHandle,
|  | iPATHREQ * | piPathRq,
|  | SSTR * | pName,
|  | int | nameLen
| ) |  |

Get the executable/library output object name for the current project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  piPathRq | Pointer to a structure containing the path request options
  pName | Pointer to a structure to containing the output object name
  nameLen | Length of the pName data

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid, writable project is loaded, and uVision is not building, downloading, or debugging

The SSTR structure is designed to contain variable length data, therefore it may be the case that the record within piPathRq actually takes up more than the static structure size.

Use this function to retrieve the path of the executable or library created by uVision when a project is built

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_LOAD | ( | int | iConnHandle,
|  | PRJDATA * | pProjectFile,
|  | int | projectFileLen
| ) |  |

Load a project into uVision

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pProjectFile | Pointer to a structure containing the path and filename of the project to load. This is a variable length structure
  projectFileLen | Size of the pProjectFile data (bytes)

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  uVision is not building, downloading, or debugging

Use this function to load a project into uVision. The current project (if any) will be saved and closed.

This is the equivalent of clicking the 'Project–>Open Project...' menu item in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_SET_DEBUG_TARGET | ( | int | iConnHandle,
|  | DBGTGTOPT * | pDbgTgtOpt
| ) |  |

Get the debug uVision target configuration

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pDbgTgtOpt | Pointer to a structure containing the debug target configuration to set

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid, writable project is loaded, and uVision is not building, downloading, or debugging

Use this function to set the debug uVision target configuration

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_SET_OPTITEM | ( | int | iConnHandle,
|  | TRNOPT * | pTrnOpt,
|  | int | trnOptLen
| ) |  |

Set a uVision project option

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pTrnOpt | Pointer to a structure containing the option item to set, and the value to set it to. This is a variable length structure, see optsel in UVSOCK.h
  trnOptLen | Size of the pTrnOpt data (bytes)

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid, writable project is loaded, and uVision is not building, downloading, or debugging

Use this function to set the value of a uVision project option.

This is the equivalent of reading settings in the 'Options for XYZ' dialogs in uVision.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_SET_OUTPUTNAME | ( | int | iConnHandle,
|  | PRJDATA * | pTargets,
|  | int | targetsLen
| ) |  |

Sets a output name in the current uVision project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pTargets | Pointer to a structure containing the target name for the target to set output name in the uVision project. This is a variable length structure
  targetsLen | Size of the pGroupFiles data (bytes)

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid, writable project is loaded, and uVision is not building, downloading, or debugging

Use this function to set an output name in the current uVision project.

This is the equivalent of setting the output name in Target Options dialog.

_UVSC_FUNC_ UVSC_STATUS UVSC_PRJ_SET_TARGET | ( | int | iConnHandle,
|  | PRJDATA * | pTargets,
|  | int | targetsLen
| ) |  |

Select a target in the current uVision project

Parameters

  iConnHandle | Handle for the connection, as returned by UVSC_OpenConnection
  pTargets | Pointer to a structure containing the target name for the target to set active in the uVision project. This is a variable length structure
  targetsLen | Size of the pGroupFiles data (bytes)

Returns
  UVSC_STATUS_SUCCESS on success, or an error code

Precondition
  UVSC_OpenConnection must have been called successfully
  A valid, writable project is loaded, and uVision is not building, downloading, or debugging

Use this function to set a target in the current uVision project to active.

This is the equivalent of clicking the 'Target' Combo Box in uVision.