# C API

This page describes the basic functions of the C API interface. For each specific protocol APIs, please refer to the corresponding sections.

group CosmicSDK C binding blocking API.

  C bindings for the CosmicSDK blocking API.

  This module exposes a C API suitable for C applications.

  Typedefs

  typedef struct CosmicSDK_Handle CosmicSDK_Handle

    Opaque handle for CosmicSDK instance.

  Functions

  CosmicSDK_Handle *CosmicSDK_Create(int timeout_ms)

    Creates a new CosmicSDK instance.

    Parameters:

      - timeout_ms – Timeout in milliseconds for operations.

    Returns:

      Handle to the created instance

  void CosmicSDK_Destroy(CosmicSDK_Handle *handle)

    Destroys a CosmicSDK instance and frees associated resources.

    Parameters:

      - handle – Handle to the instance to destroy

  void CosmicSDK_onNotification(CosmicSDK_Handle *handle, void (*callback)(const Notification*))

    Registers a notification callback for asynchronous I3C events.

    Parameters:

      - handle – Handle to the CosmicSDK instance

      - callback – Function pointer invoked with a Notification.

  bool CosmicSDK_notificationAsI3cHotJoin(const Notification *c_notification, I3cHotJoinNotification *HJInfo)

    Attempts to parse a Hot-Join notification. If `c_notification` contains a valid Hot-Join payload, the fields are decoded into `HJInfo` and the function returns `true`.

    Parameters:

      - c_notification – Pointer to a generic notification.

      - HJInfo – Output structure for parsed Hot-Join information.

    Returns:

      `true` if parsing succeeded, otherwise `false`.

  bool CosmicSDK_notificationAsI3cIbi(const Notification *c_notification, I3cIbiNotification *IBIInfo)

    Attempts to parse an In-Band Interrupt (IBI) notification. If `c_notification` contains a valid IBI payload, the fields are decoded into `IBIInfo` and the function returns `true`.

    Parameters:

      - c_notification – Pointer to a generic notification.

      - IBIInfo – Output structure for parsed IBI information.

    Returns:

      `true` if parsing succeeded, otherwise `false`.

  const char *CosmicSDK_GetVersion(void)

    Gets the CosmicSDK library version string.

    Returns a pointer to a null-terminated string containing the version number of the linked CosmicSDK library. This allows the verification at startup that the linked library matches what they were built against.

    Note

    The returned string is statically allocated and must not be freed. The pointer remains valid for the lifetime of the application.

    Returns:

      A null-terminated version string in the format “MAJOR.MINOR.PATCH”, e.g. “1.2.3”

  bool CosmicSDK_notificationAsGpio(const Notification *c_notification, GpioInterruptNotification *GpioInfo)

    Attempts to parse an GPIO Interrupt notification. If `c_notification` contains a valid GPIO payload, the fields are decoded into `GpioInfo` and the function returns `true`.

    Parameters:

      - c_notification – Pointer to a generic notification.

      - GpioInfo – Output structure for parsed GPIO information.

    Returns:

      `true` if parsing succeeded, otherwise `false`.

  bool CosmicSDK_notificationAsUartRx(const Notification *c_notification, UartRxNotification *uartInfo)

    Attempts to parse a UART notification. If `c_notification` contains a valid UART payload, the fields are decoded into `uartInfo` and the function returns `true`.

    Parameters:

      - c_notification – Pointer to a generic notification.

      - uartInfo – Output structure for parsed UART information.

    Returns:

      `true` if parsing succeeded, otherwise `false`.

  bool CosmicSDK_Connect(CosmicSDK_Handle *handle, const char *devicePath)

    Opens connection to the device.

    Parameters:

      - handle – Handle to the CosmicSDK instance

      - devicePath – Optional path to the device. Pass NULL to use default device.

    Returns:

      true if connection successful, false otherwise

  bool CosmicSDK_ConnectWithSerialNumber(CosmicSDK_Handle *handle, const char *serialNumber)

    Opens connection to the device using its serial number.

    Parameters:

      - handle – Handle to the CosmicSDK instance

      - serialNumber – Serial number of the device to connect to

    Returns:

      true if connection successful, false otherwise

  void CosmicSDK_Disconnect(CosmicSDK_Handle *handle)

    Closes connection to the device.

    Parameters:

      - handle – Handle to the CosmicSDK instance

  uint16_t CosmicSDK_GetDeviceInfo(CosmicSDK_Handle *handle, C_DeviceInfo *deviceInfoOut)

    Gets the connected device information, like Manufacturer, Product Name, FW and HW versions and Serial Number.

    Parameters:

      - handle – Handle to the CosmicSDK instance

      - deviceInfoOut – DeviceInfo object to write the connected devices data

    Returns:

      SUCCESS on success, error code otherwise

  uint16_t CosmicSDK_EnterBootMode(CosmicSDK_Handle *handle)

    Puts the device into boot mode. Once the device process the request, it immediately jumps into the bootloader. After the user has flashed the device with a firmware, a new connection needs to be done to continue using the device.

    Parameters:

      - handle – Handle to the CosmicSDK instance

    Returns:

      SUCCESS or SDK_ERROR_DISCONNECT if the device is not connected

  struct C_DeviceInfo
    #include <CosmicSDK_API_c.h>

    Structure to hold device information from C API.

    Public Members

    char *manufacturer

      Null-terminated manufacturer string.

    size_t manufacturerLength

      Manufacturer string length, excluding null terminator.

    char *productName

      Null-terminated product name string.

    size_t productNameLength

      Product name string length, excluding null terminator.

    char *serialNumber

      Null-terminated device serial number string.

    size_t serialNumberLength

      Serial number string length, excluding null terminator.

    char *fwVersion

      Null-terminated firmware version string.

    size_t fwVersionLength

      Firmware version string length, excluding null terminator.

    char *hwVersion

      Null-terminated hardware version string.

    size_t hwVersionLength

      Hardware version string length, excluding null terminator.