1 /*

     2  * Low-level protocol support for the IPC connection to the engine.

     3  */

     4 

     5 #ifndef IPCBASE_H_

     6 #define IPCBASE_H_

     7 

     8 #include <stddef.h>

     9 #include <stdbool.h>

    10 #include <stdint.h>

    11 

    12 #define IPCBASE_MAPMSG_BYTES 4097

    13 

    14 typedef enum {IPC_NOT_CONNECTED, IPC_LISTENING, IPC_CONNECTED} IpcState;

    15 

    16 struct _flib_ipcbase;

    17 typedef struct _flib_ipcbase flib_ipcbase;

    18 

    19 /**

    20  * Start an engine connection by listening on a random port. The selected port can

    21  * be queried with flib_ipcbase_port and has to be passed to the engine.

    22  *

    23  * Returns NULL on error. Destroy the created object with flib_ipcbase_destroy.

    24  *

    25  * We stop accepting new connections once a connection has been established, so you

    26  * need to create a new ipcbase in order to start a new connection.

    27  */

    28 flib_ipcbase *flib_ipcbase_create();

    29 

    30 uint16_t flib_ipcbase_port(flib_ipcbase *ipc);

    31 

    32 /**

    33  * Free resources and close sockets.

    34  */

    35 void flib_ipcbase_destroy(flib_ipcbase *ipc);

    36 

    37 /**

    38  * Determine the current connection state

    39  */

    40 IpcState flib_ipcbase_state(flib_ipcbase *ipc);

    41 

    42 /**

    43  * Receive a single message (up to 256 bytes) and copy it into the data buffer.

    44  * Returns the length of the received message, a negative value if no message could

    45  * be read.

    46  *

    47  * The first byte of a message is its content length, which is one less than the returned

    48  * value.

    49  *

    50  * Note: When a connection is closed, you probably want to call this function until

    51  * no further message is returned, to ensure you see all messages that were sent

    52  * before the connection closed.

    53  */

    54 int flib_ipcbase_recv_message(flib_ipcbase *ipc, void *data);

    55 

    56 /**

    57  * Try to receive 4097 bytes. This is the size of the reply the engine sends

    58  * when successfully queried for map data. The first 4096 bytes are a bit-packed

    59  * twocolor image of the map (256x128), the last byte is the number of hogs that

    60  * fit on the map.

    61  */

    62 int flib_ipcbase_recv_map(flib_ipcbase *ipc, void *data);

    63 

    64 int flib_ipcbase_send_raw(flib_ipcbase *ipc, const void *data, size_t len);

    65 

    66 /**

    67  * Write a single message (up to 255 bytes) to the engine. This call blocks until the

    68  * message is completely written or the connection is closed or an error occurs.

    69  *

    70  * Calling this function in a state other than IPC_CONNECTED will fail immediately.

    71  * Returns a negative value on failure.

    72  */

    73 int flib_ipcbase_send_message(flib_ipcbase *ipc, void *data, size_t len);

    74 

    75 /**

    76  * Convenience function for sending a 0-delimited string.

    77  */

    78 int flib_ipcbase_send_messagestr(flib_ipcbase *ipc, char *data);

    79 

    80 /**

    81  * Try to accept a connection. Only has an effect in state IPC_LISTENING.

    82  */

    83 void flib_ipcbase_accept(flib_ipcbase *ipc);

    84 

    85 #endif /* IPCBASE_H_ */

    86