project_files/frontlib/ipcconn.h
author Medo <smaxein@googlemail.com>
Sat, 02 Jun 2012 14:26:52 +0200
changeset 7162 fe76d24a25d7
parent 7160 c42949cfdd92
child 7171 906e72caea7b
permissions -rw-r--r--
Demo recording for the frontend library
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
7158
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
     1
/*
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
     2
 * Low-level protocol support for the IPC connection to the engine.
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
     3
 */
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
     4
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
     5
#ifndef IPCCONN_H_
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
     6
#define IPCCONN_H_
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
     7
7162
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
     8
#include "buffer.h"
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
     9
7158
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    10
#include <stddef.h>
7162
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    11
#include <stdbool.h>
7158
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    12
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    13
typedef enum {IPC_NOT_CONNECTED, IPC_LISTENING, IPC_CONNECTED} IpcConnState;
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    14
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    15
/**
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    16
 * Called by flib_init(). Initialize everything related to ipc.
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    17
 */
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    18
void flib_ipcconn_init();
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    19
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    20
/**
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    21
 * Called by flib_quit(). Free resources and shut down.
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    22
 */
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    23
void flib_ipcconn_quit();
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    24
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    25
/**
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    26
 * Start listening for a connection from the engine. The system has to be in state
7162
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    27
 * IPC_NOT_CONNECTED when calling this function, and will be in state IPC_LISTENING
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    28
 * if the function returns successfully.
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    29
 *
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    30
 * The parameter "recordDemo" can be used to control whether demo recording should
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    31
 * be enabled for this connection.
7158
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    32
 *
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    33
 * Returns the port we started listening on, or a negative value if there is an error.
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    34
 *
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    35
 * We stop listening once a connection has been established, so if you want to start
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    36
 * the engine again and talk to it you need to call this function again after the old
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    37
 * connection is closed.
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    38
 */
7162
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    39
int flib_ipcconn_start(bool recordDemo);
7158
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    40
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    41
/**
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    42
 * Close the current IPC connection and/or stop listening for an incoming one.
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    43
 * This also discards all unread messages.
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    44
 */
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    45
void flib_ipcconn_close();
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    46
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    47
/**
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    48
 * Determine the current connection state
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    49
 */
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    50
IpcConnState flib_ipcconn_state();
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    51
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    52
/**
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    53
 * Receive a single message (up to 255 bytes) and copy it into the data buffer.
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    54
 * Returns the length of the received message, a negative value if no message could
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    55
 * be read.
7162
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    56
 *
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    57
 * Note: When a connection is closed, you probably want to call this function until
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    58
 * no further message is returned, to ensure you see all messages that were sent
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    59
 * before the connection closed.
7158
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    60
 */
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    61
int flib_ipcconn_recv_message(void *data);
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    62
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    63
/**
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    64
 * Write a single message (up to 255 bytes) to the engine. This call blocks until the
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    65
 * message is completely written or the connection is closed or an error occurs.
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    66
 *
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    67
 * Calling this function in a state other than IPC_CONNECTED will fail immediately.
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    68
 * Returns a negative value on failure.
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    69
 */
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    70
int flib_ipcconn_send_message(void *data, size_t len);
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    71
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    72
/**
7162
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    73
 * Convenience function for sending a 0-delimited string.
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    74
 */
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    75
int flib_ipcconn_send_messagestr(char *data);
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    76
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    77
/**
7158
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    78
 * Call regularly to allow background work to proceed
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    79
 */
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    80
void flib_ipcconn_tick();
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
    81
7162
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    82
/**
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    83
 * Get a demo record of the last connection. This should be called after
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    84
 * the connection is closed and all messages have been received.
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    85
 *
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    86
 * If demo recording was not enabled in the last call to flib_ipcconn_start(),
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    87
 * or if the recording failed for some reason, the buffer will be empty.
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    88
 *
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    89
 * The buffer is only valid until the next call to flib_ipcconn_start() or
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    90
 * a call to flib_ipcconn_getsave() (save and demo records have some minor
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    91
 * differences, and those are performed directly on the buffer before returning it).
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    92
 */
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    93
flib_constbuffer flib_ipcconn_getdemo();
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    94
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    95
/**
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    96
 * Get a savegame record of the last connection. This should be called after
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    97
 * the connection is closed and all messages have been received.
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    98
 *
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
    99
 * If demo recording was not enabled in the last call to flib_ipcconn_start(),
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
   100
 * or if the recording failed for some reason, the buffer will be empty.
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
   101
 *
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
   102
 * The buffer is only valid until the next call to flib_ipcconn_start() or
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
   103
 * a call to flib_ipcconn_getdemo() (save and demo records have some minor
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
   104
 * differences, and those are performed directly on the buffer before returning it).
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
   105
 */
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
   106
flib_constbuffer flib_ipcconn_getsave();
fe76d24a25d7 Demo recording for the frontend library
Medo <smaxein@googlemail.com>
parents: 7160
diff changeset
   107
7158
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
   108
#endif /* IPCCONN_H_ */
a0573014ff4f Further work on the frontend library, restructuring, ...
Medo <smaxein@googlemail.com>
parents:
diff changeset
   109