Sleds/K2Client/platform_binding.h

/*
   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