The C bindings comprise a single header (uhppoted.h) and source file uhppoted.c - copy these to wherever makes it sense in your project.
The generated DLL (Windows), shared lib (Linux) or dylib (MacOS) should be placed in either the library search path for the platform:
- LD_LIBRARY (Linux)
- DYLIB_LIBRARY (MacOS)
- Windows - see Dynamic-Link Library Search Order
or in the same folder as the executable.
Examples illustrating the use of the C API can be found in the examples/c folder.
Internally, the API functions use a UHPPOTE struct that contains the information required to access a controller. The
UHPPOTE struct is initialised by invoking setup and cleaned up by invoking teardown e.g.:
setup("0.0.0.0:0", "255.255.255.255", "0.0.0.0:60001", 2500, true, &alpha, &beta, NULL);
...
...
teardown();
The API functions all return a 0 result code if the function call was successful. A non-zero result indicates
a failure and the associated text error message can be retrieved with errmsg().
Initialises the internal UHPPOTE struct that contains the information used to access the controllers.
void setup(const char *bind, const char *broadcast, const char *listen, int timeout, int debug, ...);
bind IP address:port to which to bind the UDP socket. Defaults to 0.0.0.0:0
broadcast IP address:port for broadcast UDP packets. Defaults to 255.255.255.255:60000
listen IP address:port for events from controller (unused). Defaults to 0.0.0.0:60001
timeout milliseconds to wait for a reply. Defaults to 5 seconds.
debug Displays the DLL and controller requests/responses if true.
(varargs) List of specific controllers and their associated IP addresses (e.g.for controllers
located on a different interface, a VLAN or a VPN)
The controllers vararg list is a list of controller structs, e.g.:
controller alpha = {.id = 405419896, .address = "192.168.1.100", .transport = "tcp"};
Frees any dynamically allocated memory associated with:
- the internal UHPPOTE struct created by
setup - the global error message
void teardown();
Returns the text description associated with an error if an API function returns a non-zero result. The memory
allocation is managed internally and released by teardown.
const char *errmsg();
Utility function to provide text equivalents to the following uint8_t codes:
- door control mode
- event type
- event reason
- event direction
const char *lookup(const char *category, uint8_t code, const char *locale);
category Lookup table to use ("door.mode", "event.direction", "event.type" or "event.reason")
code code from the returned information
locale Language code to use for the text lookup. Defaults to uk-en.
int get_devices(uint32_t **devices, int *N);
devices Address of controller array
N size of devices array
Returns:
- 0 if the call succeeded. The devices array will contain a list of N controller serial numbers. The devices
array is reallocated internally and the caller is responsible for freeing the associated memory.
- -1 if the call failed. The error message can be retrieved using errmsg().
int get_device(uint32_t id, struct device *controller);
id controller serial number
controller Preallocated device struct
Returns:
- 0 if the call succeeded. The device struct will be populated with the device information.
- -1 if the call failed. The error message can be retrieved using errmsg().
int set_address(uint32_t id, const char *address, const char *subnet, const char *gateway);
id controller serial number
address controller IPv4 address
subnet controller IPv4 subnet mask
gateway controller gateway IPv4 address
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int get_status(uint32_t id, struct status *status);
id controller serial number
status Preallocated status struct
Returns:
- 0 if the call succeeded. The status struct will be populated with the controller status information.
- -1 if the call failed. The error message can be retrieved using errmsg().
The controller status includes the most recently logged event but if the controller has no events
the `Event` field will have an index of 0 and all the other fields will be invalid.
int get_time(uint32_t id, char **time);
id controller serial number
time pointer for a time string
Returns:
- 0 if the call succeeded. The time variable will be initialised to a string containing the controller
date/time. The string is allocated internally and the caller is responsible for freeing the associated
memory.
- -1 if the call failed. The error message can be retrieved using errmsg().
int set_time(uint32_t id, char *time);
id controller serial number
time date/time string (YYYY-MM-dd HH:mm:ss)
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int get_listener(uint32_t id, char **time, uint8_t *interval);
id controller serial number
listener pointer to a listener address string
interval pointer to a uint8_t for the auto-send interval. Can be NULL.
Returns:
- 0 if the call succeeded. The listener variable will be initialised to a string containing the controller
listener IPv4 address. The string is allocated internally and the caller is responsible for freeing the
associated memory.
- -1 if the call failed. The error message can be retrieved using errmsg().
int set_listener(uint32_t id, char *time, uint8_t interval);
id controller serial number
listener listener IPv4 address:port
interval auto-send interval (seconds). A zero value disables auto-send.
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int get_door_control(uint32_t id, uint8_t door, struct door_control *control);
id controller serial number
door door ID [1..4]
control Preallocated door_control struct
Returns:
- 0 if the call succeeded. The control struct will be populated with the controller door configuration.
- -1 if the call failed. The error message can be retrieved using errmsg().
int set_door_control(uint32_t id, uint8_t door, uint8_t mode, uint8_t delay);
id controller serial number
door door ID [1..4]
control door configuration
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int open_door(uint32_t id, uint8_t door);
id controller serial number
door door ID [1..4]
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int get_cards(uint32_t id, int *N);
id controller serial number
N variable for number of cards stored on the controller
Returns:
- 0 if the call succeeded. N will be set to the number of cards stored on the controller.
- -1 if the call failed. The error message can be retrieved using errmsg().
int get_card(uint32_t id, uint32_t card_number, card *card);
id controller serial number
card_number card number
card Preallocated card struct
Returns:
- 0 if the call succeeded. The card struct will be populated with the card information from the controller.
- -1 if the call failed. The error message can be retrieved using errmsg().
int get_card_by_index(uint32_t id, uint32_t index, card *card);
id controller serial number
index index of card to retrieve
card Preallocated card struct
Returns:
- 0 if the call succeeded. The card struct will be populated with the card information from the controller.
- -1 if the call failed. The error message can be retrieved using errmsg().
int put_card(uint32_t id, uint32_t card_number, const char *from, const char *to, const uint8_t doors[4], uint32_t PIN);
id controller serial number
card_number card number
from card valid from date, inclusive (YYYY-MM-dd)
to card valid until, inclusive (YYYY-MM-dd)
doors 4 byte array with card permissions
PIN reader keypad PIN ([0..999999], 0 for 'no PIN')
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int delete_card(uint32_t id, uint32_t card_number);
id controller serial number
card_number card number
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int delete_cards(uint32_t id);
id controller serial number
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int get_event_index(uint32_t id, uint32_t *index);
id controller serial number
index variable for controller event index
Returns:
- 0 if the call succeeded. index will be set to the controller event index.
- -1 if the call failed. The error message can be retrieved using errmsg().
int set_event_index(uint32_t id, uint32_t index);
id controller serial number
index controller event index
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int get_event(uint32_t id, uint32_t index, event *event);
id controller serial number
index index of event to retrieve
event Preallocated event struct
Returns:
- 0 if the call succeeded. The event struct will be populated with the event information
from the controller.
- -1 if the call failed. The error message can be retrieved using errmsg().
int record_special_events(uint32_t id, bool enabled);
id controller serial number
enabled Enables/disables recording of door, etc events
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int get_time_profile(uint32_t id, uint8_t profile_id, time_profile *profile);
id controller serial number
profile_id ID [2..254] of time profile to retrieve
profile Preallocated time_profile struct
Returns:
- 0 if the call succeeded. The profile struct will be populated with the time profile information
from the controller.
- -1 if the call failed. The error message can be retrieved using errmsg().
int set_time_profile(uint32_t id, time_profile *profile);
id controller serial number
profile time_profile struct initialised with the time profile to store on the controller.
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int clear_time_profiles(uint32_t id);
id controller serial number
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int add_task(uint32_t id, task *task);
id controller serial number
task task struct initialised with the task to store on the controller.
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int refresh_tasklist(uint32_t id);
id controller serial number
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int clear_tasklist(uint32_t id);
id controller serial number
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int set_pc_control(uint32_t controller, bool enabled);
controller controller serial number
enabled enables/disables PC control
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int set_interlock(uint32_t controller, uint8_t interlock);
controller controller serial number
interlock controller door interlock mode
0: no interlock
1: doors 1&2
2: doors 3&4
3: doors 1&2,3&4
4: doors 1&2&3
8: doors 1&2&3&4
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int activate_keypads(uint32_t controller, bool reader1, bool reader2, bool reader3, bool reader4);
controller controller serial number
reader1 activates/deactivates access keypad for reader 1
reader2 activates/deactivates access keypad for reader 2
reader3 activates/deactivates access keypad for reader 3
reader4 activates/deactivates access keypad for reader 4
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int set_door_passcodes(uint32_t controller, uint8_t door, uint32_t passcode1, uint32_t passcode2, uint32_t passcode3, uint32_t passcode4);
controller controller serial number
door door ID [1..4]
passcode1 PIN code in the range [1..999999] or 0 (for none)
passcode2 PIN code in the range [1..999999] or 0 (for none)
passcode3 PIN code in the range [1..999999] or 0 (for none)
passcode4 PIN code in the range [1..999999] or 0 (for none)
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int restore-default-parameters(uint32_t controller);
controller controller serial number
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
int listen_events(on_event callback, bool *listening, bool *stop, on_error onerror, void *userdata);
callback callback function invoked to process received events
listening set to 'true' when the listen function is initialised and listening
stop set to 'true' by the parent function to terminate the listen function
onerror callback function to report event errors
userdata (optional) pointer to non-specific data. Returned 'as is' by the callback function.
The callback functions are defined as:
typedef void (*on_event)(const struct ListenEvent evt, void *userdata);
typedef void (*on_error)(const char *err);
Returns:
- 0 if the call succeeded.
- -1 if the call failed. The error message can be retrieved using errmsg().
Container struct for use with the setup function.
typedef struct controller {
uint32_t id;
const char *address;
const char *transport;
} controller;
The transport field is optional - valid values are "udp" or "tcp", defaulting to "udp" if the value is NULL.
Container struct for the controller information retrieved by get_device
typedef struct device {
uint32_t ID;
char address[16];
char subnet[16];
char gateway[16];
char MAC[18];
char version[6];
char date[11];
} device;
Container struct for the event information retrieved by get_event.
typedef struct event {
char timestamp[20];
uint32_t index;
uint8_t eventType;
bool granted;
uint8_t door;
uint8_t direction;
uint32_t card;
uint8_t reason;
} event;
Container struct for the controller status information retrieved by get_status
The controller status includes the most recently logged event but if the controller has no events
the Event field will have an index of 0 and all the other fields will be invalid.
typedef struct status {
uint32_t ID;
char sysdatetime[20];
bool doors[4];
bool buttons[4];
uint8_t relays;
uint8_t inputs;
uint8_t syserror;
uint8_t info;
uint32_t seqno;
event evt;
} status;
Container struct for door configuration for get_door_control and set_door_control.
typedef struct door_control {
uint8_t mode;
uint8_t delay;
} door_control;
Container struct for card information retrieved by get_card and get_card_by_index.
typedef struct card {
uint32_t card_number;
char from[11];
char to[11];
uint8_t doors[4];
uint32_t PIN;
} card;
Container struct for time profile information retrieved/set by get_time_profile and
set_time_profile.
typedef struct time_profile {
uint8_t ID;
uint8_t linked;
char from[11];
char to[11];
bool monday;
bool tuesday;
bool wednesday;
bool thursday;
bool friday;
bool saturday;
bool sunday;
char segment1start[6];
char segment1end[6];
char segment2start[6];
char segment2end[6];
char segment3start[6];
char segment3end[6];
} time_profile;
Container struct for the task information required for add_task.
typedef struct task {
uint8_t task;
uint8_t door;
char from[11];
char to[11];
bool monday;
bool tuesday;
bool wednesday;
bool thursday;
bool friday;
bool saturday;
bool sunday;
char at[6];
uint8_t cards;
} task;
Container struct for a received event.
typedef struct ListenEvent {
uint32_t controller;
const char *timestamp;
uint32_t index;
uint8_t event;
bool granted;
uint8_t door;
uint8_t direction;
uint32_t card;
uint8_t reason;
} ListenEvent;