ip_connection.h

/*
 * Copyright (C) 2012-2013 Matthias Bolte <matthias@tinkerforge.com>
 * Copyright (C) 2011 Olaf Lüke <olaf@tinkerforge.com>
 *
 * Redistribution and use in source and binary forms of this file,
 * with or without modification, are permitted.
 */

#ifndef IP_CONNECTION_H
#define IP_CONNECTION_H

#ifndef __STDC_LIMIT_MACROS
    #define __STDC_LIMIT_MACROS
#endif
#include <stdint.h>
#include <string.h>
#include <stdlib.h>

#if !defined __cplusplus && defined __GNUC__
    #include <stdbool.h>
#endif

#ifdef _WIN32
    #ifndef WIN32_LEAN_AND_MEAN
        #define WIN32_LEAN_AND_MEAN
    #endif
    #include <windows.h>
#else
    #include <pthread.h>
    #include <semaphore.h>
#endif

enum {
    E_OK = 0,
    E_TIMEOUT = -1,
    E_NO_STREAM_SOCKET = -2,
    E_HOSTNAME_INVALID = -3,
    E_NO_CONNECT = -4,
    E_NO_THREAD = -5,
    E_NOT_ADDED = -6, // unused since v2.0
    E_ALREADY_CONNECTED = -7,
    E_NOT_CONNECTED = -8,
    E_INVALID_PARAMETER = -9, // error response from device
    E_NOT_SUPPORTED = -10, // error response from device
    E_UNKNOWN_ERROR_CODE = -11 // error response from device
};

#ifdef IPCON_EXPOSE_INTERNALS

typedef struct _Socket Socket;

typedef struct {
#ifdef _WIN32
    CRITICAL_SECTION handle;
#else
    pthread_mutex_t handle;
#endif
} Mutex;

void mutex_create(Mutex *mutex);

void mutex_destroy(Mutex *mutex);

void mutex_lock(Mutex *mutex);

void mutex_unlock(Mutex *mutex);

typedef struct {
#ifdef _WIN32
    HANDLE handle;
#else
    pthread_cond_t condition;
    pthread_mutex_t mutex;
    bool flag;
#endif
} Event;

typedef struct {
#ifdef _WIN32
    HANDLE handle;
#else
    sem_t object;
    sem_t *pointer;
#endif
} Semaphore;

typedef void (*ThreadFunction)(void *opaque);

typedef struct {
#ifdef _WIN32
    HANDLE handle;
    DWORD id;
#else
    pthread_t handle;
#endif
    ThreadFunction function;
    void *opaque;
} Thread;

typedef struct {
    Mutex mutex;
    int used;
    int allocated;
    uint32_t *keys;
    void **values;
} Table;

typedef struct _QueueItem {
    struct _QueueItem *next;
    int kind;
    void *data;
    int length;
} QueueItem;

typedef struct {
    Mutex mutex;
    Semaphore semaphore;
    QueueItem *head;
    QueueItem *tail;
} Queue;

#if defined _MSC_VER || defined __BORLANDC__
    #pragma pack(push)
    #pragma pack(1)
    #define ATTRIBUTE_PACKED
#elif defined __GNUC__
    #ifdef _WIN32
        // workaround struct packing bug in GCC 4.7 on Windows
        // http://gcc.gnu.org/bugzilla/show_bug.cgi?id=52991
        #define ATTRIBUTE_PACKED __attribute__((gcc_struct, packed))
    #else
        #define ATTRIBUTE_PACKED __attribute__((packed))
    #endif
#else
    #error unknown compiler, do not know how to enable struct packing
#endif

typedef struct {
    uint32_t uid;
    uint8_t length;
    uint8_t function_id;
    uint8_t sequence_number_and_options;
    uint8_t error_code_and_future_use;
} ATTRIBUTE_PACKED PacketHeader;

typedef struct {
    PacketHeader header;
    uint8_t payload[64];
    uint8_t optional_data[8];
} ATTRIBUTE_PACKED Packet;

#if defined _MSC_VER || defined __BORLANDC__
    #pragma pack(pop)
#endif
#undef ATTRIBUTE_PACKED

#endif // IPCON_EXPOSE_INTERNALS

typedef struct _IPConnection IPConnection;
typedef struct _IPConnectionPrivate IPConnectionPrivate;
typedef struct _Device Device;
typedef struct _DevicePrivate DevicePrivate;

#ifdef IPCON_EXPOSE_INTERNALS

typedef struct _CallbackContext CallbackContext;

#endif

typedef void (*EnumerateCallbackFunction)(const char *uid,
                                          const char *connected_uid,
                                          char position,
                                          uint8_t hardware_version[3],
                                          uint8_t firmware_version[3],
                                          uint16_t device_identifier,
                                          uint8_t enumeration_type,
                                          void *user_data);
typedef void (*ConnectedCallbackFunction)(uint8_t connect_reason,
                                          void *user_data);
typedef void (*DisconnectedCallbackFunction)(uint8_t disconnect_reason,
                                             void *user_data);

#ifdef IPCON_EXPOSE_INTERNALS

typedef void (*CallbackWrapperFunction)(DevicePrivate *device_p, Packet *packet);

#endif

struct _Device {
    DevicePrivate *p;
};

#ifdef IPCON_EXPOSE_INTERNALS

#define DEVICE_NUM_FUNCTION_IDS 256

struct _DevicePrivate {
    uint32_t uid;

    IPConnectionPrivate *ipcon_p;

    uint8_t api_version[3];

    Mutex request_mutex;

    uint8_t expected_response_function_id; // protected by request_mutex
    uint8_t expected_response_sequence_number; // protected by request_mutex
    Mutex response_mutex;
    Packet response_packet; // protected by response_mutex
    Event response_event;
    int response_expected[DEVICE_NUM_FUNCTION_IDS];

    void *registered_callbacks[DEVICE_NUM_FUNCTION_IDS];
    void *registered_callback_user_data[DEVICE_NUM_FUNCTION_IDS];
    CallbackWrapperFunction callback_wrappers[DEVICE_NUM_FUNCTION_IDS];
};

enum {
    DEVICE_RESPONSE_EXPECTED_INVALID_FUNCTION_ID = 0,
    DEVICE_RESPONSE_EXPECTED_ALWAYS_TRUE, // getter
    DEVICE_RESPONSE_EXPECTED_ALWAYS_FALSE, // callback
    DEVICE_RESPONSE_EXPECTED_TRUE, // setter
    DEVICE_RESPONSE_EXPECTED_FALSE // setter, default
};

void device_create(Device *device, const char *uid,
                   IPConnectionPrivate *ipcon_p, uint8_t api_version_major,
                   uint8_t api_version_minor, uint8_t api_version_release);

void device_destroy(Device *device);

int device_get_response_expected(DevicePrivate *device_p, uint8_t function_id,
                                 bool *ret_response_expected);

int device_set_response_expected(DevicePrivate *device_p, uint8_t function_id,
                                 bool response_expected);

int device_set_response_expected_all(DevicePrivate *device_p, bool response_expected);

void device_register_callback(DevicePrivate *device_p, uint8_t id, void *callback,
                              void *user_data);

int device_get_api_version(DevicePrivate *device_p, uint8_t ret_api_version[3]);

int device_send_request(DevicePrivate *device_p, Packet *request, Packet *response);

#endif // IPCON_EXPOSE_INTERNALS

enum {
    IPCON_CALLBACK_ENUMERATE = 253,
    IPCON_CALLBACK_CONNECTED = 0,
    IPCON_CALLBACK_DISCONNECTED = 1
};

enum {
    IPCON_ENUMERATION_TYPE_AVAILABLE = 0,
    IPCON_ENUMERATION_TYPE_CONNECTED = 1,
    IPCON_ENUMERATION_TYPE_DISCONNECTED = 2
};

enum {
    IPCON_CONNECT_REASON_REQUEST = 0,
    IPCON_CONNECT_REASON_AUTO_RECONNECT = 1
};

enum {
    IPCON_DISCONNECT_REASON_REQUEST = 0,
    IPCON_DISCONNECT_REASON_ERROR = 1,
    IPCON_DISCONNECT_REASON_SHUTDOWN = 2
};

enum {
    IPCON_CONNECTION_STATE_DISCONNECTED = 0,
    IPCON_CONNECTION_STATE_CONNECTED = 1,
    IPCON_CONNECTION_STATE_PENDING = 2 // auto-reconnect in progress
};

struct _IPConnection {
    IPConnectionPrivate *p;
};

#ifdef IPCON_EXPOSE_INTERNALS

#define IPCON_NUM_CALLBACK_IDS 256

struct _IPConnectionPrivate {
#ifdef _WIN32
    bool wsa_startup_done; // protected by socket_mutex
#endif

    char *host;
    uint16_t port;

    uint32_t timeout; // in msec

    bool auto_reconnect;
    bool auto_reconnect_allowed;
    bool auto_reconnect_pending;

    Mutex sequence_number_mutex;
    uint8_t next_sequence_number; // protected by sequence_number_mutex

    Table devices;

    void *registered_callbacks[IPCON_NUM_CALLBACK_IDS];
    void *registered_callback_user_data[IPCON_NUM_CALLBACK_IDS];

    Mutex socket_mutex;
    Socket *socket; // protected by socket_mutex
    uint64_t socket_id; // protected by socket_mutex

    bool receive_flag;
    Thread receive_thread; // protected by socket_mutex

    CallbackContext *callback;

    bool disconnect_probe_flag;
    Thread disconnect_probe_thread; // protected by socket_mutex
    Event disconnect_probe_event;

    Semaphore wait;
};

#endif // IPCON_EXPOSE_INTERNALS

void ipcon_create(IPConnection *ipcon);

void ipcon_destroy(IPConnection *ipcon);

int ipcon_connect(IPConnection *ipcon, const char *host, uint16_t port);

int ipcon_disconnect(IPConnection *ipcon);

int ipcon_get_connection_state(IPConnection *ipcon);

void ipcon_set_auto_reconnect(IPConnection *ipcon, bool auto_reconnect);

bool ipcon_get_auto_reconnect(IPConnection *ipcon);

void ipcon_set_timeout(IPConnection *ipcon, uint32_t timeout);

uint32_t ipcon_get_timeout(IPConnection *ipcon);

int ipcon_enumerate(IPConnection *ipcon);

void ipcon_wait(IPConnection *ipcon);

void ipcon_unwait(IPConnection *ipcon);

void ipcon_register_callback(IPConnection *ipcon, uint8_t id,
                             void *callback, void *user_data);

#ifdef IPCON_EXPOSE_INTERNALS

int packet_header_create(PacketHeader *header, uint8_t length,
                         uint8_t function_id, IPConnectionPrivate *ipcon_p,
                         DevicePrivate *device_p);

uint8_t packet_header_get_sequence_number(PacketHeader *header);

void packet_header_set_sequence_number(PacketHeader *header,
                                       uint8_t sequence_number);

uint8_t packet_header_get_response_expected(PacketHeader *header);

void packet_header_set_response_expected(PacketHeader *header,
                                         uint8_t response_expected);

uint8_t packet_header_get_error_code(PacketHeader *header);

int16_t leconvert_int16_to(int16_t native);

uint16_t leconvert_uint16_to(uint16_t native);

int32_t leconvert_int32_to(int32_t native);

uint32_t leconvert_uint32_to(uint32_t native);

int64_t leconvert_int64_to(int64_t native);

uint64_t leconvert_uint64_to(uint64_t native);

float leconvert_float_to(float native);

int16_t leconvert_int16_from(int16_t little);

uint16_t leconvert_uint16_from(uint16_t little);

int32_t leconvert_int32_from(int32_t little);

uint32_t leconvert_uint32_from(uint32_t little);

int64_t leconvert_int64_from(int64_t little);

uint64_t leconvert_uint64_from(uint64_t little);

float leconvert_float_from(float little);

#endif // IPCON_EXPOSE_INTERNALS

#endif