179 lines
6.5 KiB
C
179 lines
6.5 KiB
C
/*
|
|
Copyright (c) 2013 IOnU Security Inc. All rights reserved
|
|
Created August 2013 by Kendrick Webster
|
|
|
|
platform_binding.h - header for platform adapter layer of K2 socket
|
|
notifier UDP client library
|
|
|
|
***** Overview *****
|
|
This module implements a layer below the application (library API)
|
|
and above the K2Client.c module (the low-layer communications driver).
|
|
It encapsulates platform-specific code (with support for multiple
|
|
platforms) implementing thread, socket, and timer services needed by
|
|
the K2Client.c module. It also implements hostname lookup, load
|
|
balancing (random), and failover.
|
|
|
|
***** Threading *****
|
|
This module spawns its own internal thread. Its interface functions
|
|
complete quickly and are safe to call from arbitrary threads.
|
|
|
|
Callbacks are called by this module's internal thread or by the
|
|
caller's thread (the thread calling K2_Start() et. al.)
|
|
|
|
***** API *****
|
|
This module exposes the following API to library users:
|
|
|
|
Function Usage
|
|
-----------------------------------------------------------------------
|
|
K2_Start Sets parameters and starts connection
|
|
K2_Stop Logs out and closes connection
|
|
K2_Restart Restarts connection with previous parameters
|
|
K2_StatusSelect Registers interest in device status within offices
|
|
K2_Poll_DB Signal from CloudGuard: new data in database
|
|
K2_GetStats Fetch daemon memory and CPU usage statistics
|
|
|
|
Callback registered via K2_Init(...):
|
|
|
|
Callback Condition
|
|
-----------------------------------------------------------------------
|
|
onMessage A message has been received from the server or a
|
|
network connection event or error occurred (see the
|
|
k2_message_callback_t comments for details)
|
|
*/
|
|
#pragma once
|
|
#include <stdint.h>
|
|
#include "K2IPC.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* -------------- callback types ---------------- */
|
|
/*
|
|
k2_message_callback_t - callback for handling messages and events
|
|
|
|
<message> - a string representing the message or event.
|
|
The string begins with a colon-delimited field indicating what the
|
|
remainder of the string means:
|
|
|
|
'info:' - the 'info' field from MongoDB queue on server
|
|
|
|
'k2cli:' - a K2 client event ("logged out", "connection lost", etc.)
|
|
|
|
'status:' - <status value>:deviceURN for a device with a status change
|
|
within an office subscribed via K2_StatusSelect(offices).
|
|
|
|
<status value> may be one of the following:
|
|
'online' - device is online
|
|
'offline' - device is offline
|
|
Example: 'online:urn:sl:000000:F4685A6B:8F4D:'
|
|
|
|
callee must copy this string to a local buffer before returning
|
|
(the string that is pointed to is freed after returning)
|
|
*/
|
|
#define K2CLI_STRING_CONSTANTS_EXTRACT
|
|
#define K2_MESSAGE_PREFIX_INTERNAL "k2cli:"
|
|
#define K2_MESSAGE_PREFIX_FROM_CLOUD "info:"
|
|
#define K2_MESSAGE_PREFIX_DEVICE_STATUS "status:"
|
|
#define K2_MESSAGE_2ND_PREFIX_FOR_ERRORS "ERROR: "
|
|
#undef K2CLI_STRING_CONSTANTS_EXTRACT
|
|
typedef void (* k2_message_callback_t)(const char* message);
|
|
|
|
|
|
/* -------------- functions ---------------- */
|
|
/*
|
|
Start - sets parameters and logs in to daemon
|
|
|
|
<urn> the cloudguard URN for this client device
|
|
|
|
<servers> list of K2Daemon servers with '|' as delimiter, for example:
|
|
"cg2.ionu.com:32000|cg2.ionu.com:80|cg3.ionu.com:32000|cg3.ionu.com:80"
|
|
|
|
<onMessage> message handler callback
|
|
*/
|
|
#define K2CLI_CHAR_CONSTANTS_EXTRACT
|
|
#define K2_SERVERS_SUBSTRING_DELIMITER '|'
|
|
#define K2_SERVERS_PORT_DELIMITER ':'
|
|
#undef K2CLI_CHAR_CONSTANTS_EXTRACT
|
|
void K2_Start(
|
|
const char* urn,
|
|
const char* servers,
|
|
k2_message_callback_t onMessage);
|
|
|
|
/*
|
|
Stop - logs out, closes connection
|
|
*/
|
|
void K2_Stop(void);
|
|
|
|
/*
|
|
Restart - resumes connection
|
|
*/
|
|
void K2_Restart(void);
|
|
|
|
/*
|
|
StatusSelect - Subscribes to a group of offices for device status notifications.
|
|
|
|
<offices> is a comma-delimited list of 0 or more office URNs, for example:
|
|
"urn:sl:000000:F4685A6B::,urn:sl:000000:58B520CE::,urn:sl:000000:8F099CC2::".
|
|
Passing NULL or an empty string ("") clears subscriptions.
|
|
|
|
When logged in, if the status of a device in a subscribed office changes, onMessage
|
|
will be called with a 'status:' message (see k2_message_callback_t comments).
|
|
|
|
This function may be called at any time (logged in or not). Subsequent calls to
|
|
this function replace (rather than add to) the subscribed group. The subscribed
|
|
group persists (in client memory) across K2_Stop(), K2_Start(), and K2_Restart()
|
|
calls. It is cleared when this library is loaded (client application launched).
|
|
|
|
Server memory usage is automatically minimized. The subscription is cleared from
|
|
server memory when a client logs out or times out. The client library sends the
|
|
list to the server after the client connects for any reason (including failover or
|
|
reconnect after a connectivity interruption).
|
|
*/
|
|
#define K2_OFFICE_URN_DELIMITER K2IPC_OFFICE_DELIMITER
|
|
void K2_StatusSelect(const char* offices);
|
|
|
|
|
|
/* ------------------- Logging verbosity ------------------- */
|
|
typedef enum
|
|
{
|
|
LOG_LEVEL_FATAL,
|
|
LOG_LEVEL_ERROR,
|
|
LOG_LEVEL_WARNING,
|
|
LOG_LEVEL_INFORMATIONAL,
|
|
LOG_LEVEL_DEBUG,
|
|
LOG_LEVEL_VERBOSE
|
|
}
|
|
log_verbosity_level_t;
|
|
void K2_SetLogVerbosityLevel(log_verbosity_level_t level); // ok to call at any time
|
|
|
|
|
|
/* -------------- CloudGuard special API functions ---------------- */
|
|
|
|
/*
|
|
Poll_DB - tells the daemon that the database has updated data
|
|
(special - used only by the CloudGuard client)
|
|
*/
|
|
void K2_Poll_DB(void);
|
|
|
|
/*
|
|
K2_GetStats - fills caller's buffer with a JSON string containing K2Daemon CPU
|
|
and memory usage statistics. Returns non-zero (TRUE) if successful.
|
|
(note: this is a synchronous (blocking) function)
|
|
*/
|
|
int K2_GetStats(char* buf, unsigned int bufsize);
|
|
|
|
|
|
/* -------------- Non-API functions ---------------- */
|
|
/* These functions support other K2Client modules */
|
|
|
|
/* message upcalls, these pass messages up to the library client using K2_MESSAGE_PREFIX_INTERNAL */
|
|
void upcall_error(const char* where, int errnum); /* errnum is looked up using strerror() or other platform-specific equivalents */
|
|
void upcall_errno(const char* where); /* calls upcall_error with errno (or other platform-specific equivalent) for last C library or socket error */
|
|
void upcall_error_string(const char* where, const char* error_string);
|
|
void upcall_k2cli_message(const char* message); /* for generic K2Client (K2_MESSAGE_PREFIX_INTERNAL) messages */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|