Using the C API

The C API is separated into a set of data structures and functions. You only need to include the sscamapi.h header in your code.

Keep the following in mind:

  • On Windows, include the sscmapi.dll and sscmapi.lib files in your Visual Studio project.
  • On Mac, link against the libsscmapi.dylib file.
  • On Linux, link against the libsscmapi.so file.
  • The C API uses UTF-8 encoding for all string parameters and return values. If you have strings in other Unicode encodings, you must convert them to UTF-8 before passing them to API functions.

Examples 

Source code examples are included in the C API documentation for every function used to interact with the Surround SCM Server. Refer to these examples for information about specific operations. Examples are located in the API/docs/C/samples directory in the Surround SCM application directory.

Key concepts

All calls use an SSCMContext structure as the container that holds data for the currently connected session. The pMainline and pBranch members are used by other functions to identify the mainline and branch to perform operations against. The cookie member is initially populated inside the sscm_connect function. The statusCallback function pointer is optional, but if it is set, the API uses it to return string-based status messages about long-running operations.

You typically begin using the API with a call to sscm_connect, which establishes the initial SSCMContext. You then set the context to mainline and branch currently used. After all calls are complete, make a final call to sscm_disconnect to close the session.

Pay close attention to the sscm_free_xxxx calls (e.g., sscm_free_branch, sscm_free_file_props, etc.) to ensure memory is released correctly. Refer to the examples for each call in the API documentation to determine when memory management calls are needed.

SSCMResult result code

All calls also return an SSCMResult result code, which indicates the status of the last call made and defines several enumerated values. You can use the sscm_get_last_error function to return a string based on the error and code generated by the server. Only the server error string for the last error is stored by the library. The call string is cleared on the next successful function call.