Creating C API Objects

The C API uses C mechanisms at the interface level. C API objects are created with CreateXXX functions, which return a handle to the object. The handle is used as the first parameter to functions that perform methods on the object. The objects must be destroyed with ReleaseXXX functions. For example, use the following code to create a session object to interact with the Host Integrator Server:

  SessionHandle hSess;
  hSess = CreateSession();
  ReleaseSession(hSess);
  

The C API functions use the following four basic types:

• int is used for boolean values.
• long is used for numeric values.
• CharType * is used for string values and is defined as char *, but may also be defined as wchar_t in the future.
• Handles are defined for each of the C API objects. The handles are all defined as void *, so a handle can be assigned to any other handle type; however, the handle will be checked for the proper type whenever it is used in a functional call.

Note: CharType * and handle parameters that are not required may be 0 or null.

  int nRet;
  nRet = ConnectToModel(hSess, "localhost", "CCSDemo", 
  "bjones", "bjones", 0);
  if (nRet)
      Disconnect(hSess, 0);

Strings are returned from the C API by passing a string buffer and the buffer's length into a function. The actual length of the AppConn string is returned. The C API function will only copy into the buffer up to the length that was given. If the buffer is 0 or null then nothing will be copied. If the size of the buffer that is being returned is known, then the C API function can be called with a static or preallocated buffer. If the size of the buffer is not known, the C API function can be called with a null buffer to get the length of the string. Then, a string buffer can be allocated of that length, and the C API function can be called with that allocated buffer. For example:

  long nLen;
  char szCurrentEntity[80];
  char *pszCurrentEntity;
  nLen = GetCurrentEntity(hSess, szCurrentEntity, sizeof(szCurrentEntity));
  nLen = GetCurrentEntity(hSess, 0, 0);
  pszCurrentEntity = new char[nLen + 1];
  GetCurrentEntity(hSess, pszCurrentEntity, nLen); 
  Delete [] pszCurrentEntity;
  

Handles to objects that are returned from C API functions must be released just like objects that are created explicitly. For example:

  StringMapHandle hVariables;
  hVariables = GetModelVariables(hSess);
  ReleaseStringMap(hVariables);