SDAI Usage Procedure

IFC SDK API contains a set of functions that implements SDAI functionality. To get additional information about these functions, see the SDAI functions documentation.

All SDAI functions have either "_sdai" or "sdai" prefixes in their names. Functions that start with the "_sdai" prefix are special IFC SDK utility functions, which are not specified in the SDAI specification.

SDAI operations are performed within an SDAI session. When an operation fails, the appropriate error code can be retrieved by using the sdaiErrorQuery() function. You can use this function to determine what went wrong during the SDAI session and report the error details to a user. In cases when the operation is successful, this function returns the sdaiNO_ERR value.

Error codes are collected at the error query using FIFO rules ("First In - First Out"). Each call of the sdaiErrorQuery() function removes the last error state from the error queue.

A common workflow with the SDAI programming interface in IFC SDK contains the following steps:

Create a new SDAI session by calling the sdaiOpenSession() function:
```
SdaiSession session = sdaiOpenSession();
if ((!session) || (sdaiErrorQuery() != sdaiNO_ERR))
  return;
      
```
To be sure that the session is created successfully, check the returned value and the last error.

Create and initialize the repository from an .ifc file and check the result. If the creation is successful, open it:


SdaiTestAppServices* appServices = (SdaiTestAppServices*)pHostApp;
if(!appServices)
  return;

OdString pathToFile = L"Ifc4/rac_basic_sample_project_4_low.ifc";
OdAnsiString pathToFileDirectory = static_cast < OdAnsiString > (appServices->formatPathToBugDirectory(pathToFile)); 
SdaiString  sdaiPathToFileDirectory = const_cast < SdaiString > (pathToFileDirectory.c_str());

SdaiString nameRepo = "";
SdaiRep repoCreate = _sdaiCreateRepositoryFromFile(session, sdaiPathToFileDirectory, nameRepo);
if ((!repoCreate) || (sdaiErrorQuery() != sdaiNO_ERR))
  return;
repoCreate = sdaiOpenRepository(session, repoCreate);

Also see related SDAI functions:

Get a model handler from the opened repository by its name, and check the result of the open operation:
```
SdaiString modelName = "default";
SdaiAccessMode accessMode = sdaiRO;

SdaiModel model = sdaiAccessModelBN(repoCreate, modelName, accessMode);

If ((!model) || (sdaiErrorQuery() != sdaiNO_ERR))
  return;
        
```
See the sdaiAccessModelBN() function documentation for additional information.

Now the model is open in read-only mode and is ready for use. For example, you can get access to application instances.
Get access to the necessary application instance. The .ifc file loaded in the previous source code contains a set of strings in its DATA section. Each string represents an application instance and has the following structure:
```
 
#HANDLE=INSTANCE_TYPE(INSTANCE_PARAM_1_VALUE, ... , INSTANCE_PARAM_N_VALUE);
        
```
- HANDLE — Contains the handle value. The handle identifies the instance inside the DATA section.
- INSTANCE_TYPE — The instance type.
- INSTANCE_PARAM_1_VALUE — The value of the first instance parameter.
- INSTANCE_PARAM_N_VALUE — The value of the last instance parameter.
  The quantity and datatype instance parameters are specified by the schema definition.
It is possible to get access to an application instance through its handle value: use the _sdaiGetEntityById() function call as in the code fragment below:
```
//#5 = IFCAPPLICATION(#1, '2019', 'Autodesk Revit 2019 (ENU)', 'Revit');
SdaiAppInstance applicationInstance = _sdaiGetEntityById(model, 5);
if ((!applicationInstance) || (sdaiErrorQuery() != sdaiNO_ERR))
  return;
        
```
To get a handle value of the application instance, use the _sdaiGetEntityId() function.

To find out whether the application instance belongs to an appropriate instance type, call the sdaiIsInstanceOfBN() function and then check the result it returns.
```
SdaiInteger handle        = _sdaiGetEntityId(applicationInstance);
SdaiBoolean isInstanceOf  = sdaiIsInstanceOfBN(applicationInstance, "IFCAPPLICATION");

if((handle != 5) || (isInstanceOf != sdaiTRUE) || (sdaiErrorQuery() != sdaiNO_ERR))
  return;
        
```

If you do not need the model anymore, close it with the sdaiEndModelAccess() function call:


sdaiEndModelAccess(model);
if (sdaiErrorQuery() != sdaiNO_ERR)
  return;

Before finishing the application, close the open repository and the current SDAI session by calling the sdaiCloseRepository() and sdaiCloseSession() functions respectively:


sdaiCloseRepository(repoCreate);

if (sdaiErrorQuery() != sdaiNO_ERR)
  return;

sdaiCloseSession(session);

if (sdaiErrorQuery() != sdaiNO_ERR)
  return;

See Also