ip_connection.h

Go to the documentation of this file.

/*
 * Copyright (C) 2012-2014 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. See the Creative
 * Commons Zero (CC0 1.0) License for more details.
 */

#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

#ifdef __cplusplus
extern "C" {
#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;
} 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 {
        int ref_count;

        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_release(DevicePrivate *device_p);

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
#define IPCON_MAX_SECRET_LENGTH 64

typedef Device BrickDaemon;

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

        Mutex authentication_mutex; // protects authentication handshake
        uint32_t next_authentication_nonce; // protected by authentication_mutex

        Mutex devices_ref_mutex; // protects DevicePrivate.ref_count
        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;

        BrickDaemon brickd;
};

#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_authenticate(IPConnection *ipcon, const char secret[64]);

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

#ifdef __cplusplus
}
#endif

#endif