C API Reference
Complete reference for EmSACAN.h. Each function, struct, and enum has its own page with prototype, parameter descriptions, return values, and code examples.
See also the C# wrapper reference and therecommended program flow.
Library Lifecycle
EmSACAN_ConfigureCanPipeForwarder— EmSA CAN Interface — public API for the CAN Dragon DLL.EmSACAN_Shutdown— Shuts down the library; call last when finished.EmSACAN_Startup— Starts the library; call before any other API function.EmSACAN_Version— Returns the DLL version as a packed integer.
Enumeration and Connection
EmSACAN_Connect— Connects to a CAN interface by serial number.EmSACAN_Disconnect— Disconnects from a CAN interface session.EmSACAN_EnumerateInterfaces— Enumerates connected CAN interfaces.EmSACAN_GetLastError— Copies the last error message after a failed API call.
CAN Traffic
EmSACAN_GetTxQueueDepth— Returns the number of CAN frames currently queued in the hardware TX ring buffer for a port.EmSACAN_Read— Reads one CAN message from the receive path for the specified port.EmSACAN_SetCANEvents— Registers event handles signalled when new CAN data or bus errors occur on the specified port.EmSACAN_Write— Transmits one CAN message on the specified port.
Parameters
EmSACAN_CalculateTiming— Derives nominal/data bit rates and sample points from an advanced port configuration.EmSACAN_ReadParameter— Reads a device parameter (see `emsacan_parameter_t`).EmSACAN_WriteParameter— Writes a device parameter (see `emsacan_parameter_t`).
Serial Number and Firmware
EmSACAN_FirmwareUpdateBegin— Starts the CAN Dragon firmware update sequence (non-secure application image).EmSACAN_FirmwareUpdateCancel— Requests cancellation of an update started with EmSACAN_FirmwareUpdateBegin (asynchronous).EmSACAN_FirmwareUpdateGetActive— Queries whether the firmware update worker thread is running.EmSACAN_ReadFirmwareVersion— Reads firmware version information for a selected firmware slot.EmSACAN_ReadSerialNumber— Reads the device serial number as a wide string.EmSACAN_ReadSerialNumberA— Reads the device serial number as a narrow (ASCII) string.
Channel Lifecycle
EmSACAN_CloseChannel— Closes a CAN port; stops CAN communication on that port.EmSACAN_Identify— Identifies the CAN interface (visual / device indication).EmSACAN_OpenChannel— Opens the connection to a specific CAN port so traffic can flow.EmSACAN_ResetChannel— Resets a specific CAN port.
Status
EmSACAN_GetStatus— Reads the current status flags for a port.EmSACAN_IsConfigurationLocked— Reports whether channel configuration is locked for the given port.
Types and Enums
emsacan_advanced_channel_config_t— Advanced CAN port configuration (explicit timing / clock).emsacan_can_clock_temsacan_channel_config_t— Basic CAN port configuration (bitrates and flags).emsacan_channel_connection_event_t— Opaque handle to one connected CAN Dragon session (0 = invalid).emsacan_config_flags_temsacan_firmware_type_temsacan_frame_manipulation_bits_temsacan_frame_manipulation_flags_temsacan_frame_manipulation_t— Frame manipulation configuration.emsacan_frame_manipulation_txbit_temsacan_fwupdate_phase_t— Phases reported by EmSACAN_FirmwareUpdateBegin() via the progress callback.emsacan_handle_t— EmSA CAN Interface — public API for the CAN Dragon DLL.emsacan_interface_t— Describes one enumerated CAN interface.emsacan_msg_t— One received or transmitted CAN frame for the public API.emsacan_msg_type_temsacan_parameter_t— Callback for unexpected USB disconnect or reconnect of an open CAN port.emsacan_pthreads_event_t— pthread-based event object for `EmSACAN_SetCANEvents` on Linux and macOS.emsacan_result_t— EmSA CAN Interface — public API for the CAN Dragon DLL.emsacan_status_t— Firmware update progress callback.emsacan_termination_temsacan_version_t— Firmware version information.PipeCanMessage— Fixed-size record for named-pipe forwarding (little-endian, Windows DLL).PipeCanMessage
Constants
EMSACAN_MAX_CHANNELS— Maximum number of CAN ports per interface supported by this SDK release.EMSACAN_MAX_DESCRIPTION_LEN— Maximum length (wchar_t units) for description fields in `emsacan_interface_t`.EMSACAN_MAX_SERIAL_NUMBER_LEN— Pack a struct to 1-byte alignment (Clang/GCC). */ #define PACK(__Declaration__) __Declaration__ __attribute__((__packed__)) #endif #if defined(_MSC_VER) && !defined(__clang__) /*@brief Pack a struct to 1-byte alignment (MSVC, pragma-based). */ #define PACK(__Declaration__) \ __pragma(pack(push, 1)) __Declaration__ __pragma(pack(pop)) #endif /*@brief Maximum length (wchar_t units) for serial number fields in `emsacan_interface_t`.EMSACAN_MSGSTAT_FORCEBL_BIT— Supported bits in the emsacan_msg_t stat field - the Force BL input pin (1 = high, 0 = low)EMSACAN_MSGSTAT_GPI_BIT— Supported bits in the emsacan_msg_t stat field - the general purpose input pin (1 = high, 0 = low)EMSACAN_PIPE_CAN_MESSAGE_BYTES— Function result codes.EMSACAN_SERIAL_NUMBER_LEN— Maximum length of a serial number in characters (buffers for read APIs).