hedgewars: project_files/frontlib/ipc/ipcbase.h@613998625a3c (annotated)

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
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	5	#ifndef IPCBASE_H_
613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	6	#define IPCBASE_H_
7162 fe76d24a25d7 Demo recording for the frontend library Medo <smaxein@googlemail.com> parents: 7160 diff changeset	7
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	8	#include <stddef.h>
7162 fe76d24a25d7 Demo recording for the frontend library Medo <smaxein@googlemail.com> parents: 7160 diff changeset	9	#include <stdbool.h>
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	10	#include <stdint.h>
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	11
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	12	#define IPCBASE_MAPMSG_BYTES 4097
7175 038e3415100a Added ini reading/writing for game schemes to the frontend lib Medo <smaxein@googlemail.com> parents: 7173 diff changeset	13
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	14	typedef enum {IPC_NOT_CONNECTED, IPC_LISTENING, IPC_CONNECTED} IpcState;
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	15
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	16	struct _flib_ipcbase;
613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	17	typedef struct _flib_ipcbase flib_ipcbase;
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	18
a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	19	/**
7171 906e72caea7b frontlib refactoring Medo <smaxein@googlemail.com> parents: 7162 diff changeset	20	* Start an engine connection by listening on a random port. The selected port can
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	21	* be queried with flib_ipcbase_port and has to be passed to the engine.
7162 fe76d24a25d7 Demo recording for the frontend library Medo <smaxein@googlemail.com> parents: 7160 diff changeset	22	*
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	23	* Returns NULL on error. Destroy the created object with flib_ipcbase_destroy.
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	24	*
7171 906e72caea7b frontlib refactoring Medo <smaxein@googlemail.com> parents: 7162 diff changeset	25	* We stop accepting new connections once a connection has been established, so you
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	26	* need to create a new ipcbase in order to start a new connection.
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	27	*/
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	28	flib_ipcbase *flib_ipcbase_create();
7171 906e72caea7b frontlib refactoring Medo <smaxein@googlemail.com> parents: 7162 diff changeset	29
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	30	uint16_t flib_ipcbase_port(flib_ipcbase *ipc);
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	31
a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	32	/**
7224 5143861c83bd Cleanup, refactoring and generally more development in the frontlib Medo <smaxein@googlemail.com> parents: 7179 diff changeset	33	* Free resources and close sockets.
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	34	*/
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	35	void flib_ipcbase_destroy(flib_ipcbase *ipc);
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	36
a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	37	/**
a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	38	* Determine the current connection state
a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	39	*/
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	40	IpcState flib_ipcbase_state(flib_ipcbase *ipc);
7158 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	/**
7173 7c2eb284f9f1 Frontlib: Work on the callback mechanisms for IPC Medo <smaxein@googlemail.com> parents: 7171 diff changeset	43	* Receive a single message (up to 256 bytes) and copy it into the data buffer.
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	44	* 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	45	* be read.
7162 fe76d24a25d7 Demo recording for the frontend library Medo <smaxein@googlemail.com> parents: 7160 diff changeset	46	*
7173 7c2eb284f9f1 Frontlib: Work on the callback mechanisms for IPC Medo <smaxein@googlemail.com> parents: 7171 diff changeset	47	* The first byte of a message is its content length, which is one less than the returned
7c2eb284f9f1 Frontlib: Work on the callback mechanisms for IPC Medo <smaxein@googlemail.com> parents: 7171 diff changeset	48	* value.
7c2eb284f9f1 Frontlib: Work on the callback mechanisms for IPC Medo <smaxein@googlemail.com> parents: 7171 diff changeset	49	*
7162 fe76d24a25d7 Demo recording for the frontend library Medo <smaxein@googlemail.com> parents: 7160 diff changeset	50	* 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	51	* 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	52	* before the connection closed.
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	53	*/
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	54	int flib_ipcbase_recv_message(flib_ipcbase ipc, void data);
7171 906e72caea7b frontlib refactoring Medo <smaxein@googlemail.com> parents: 7162 diff changeset	55
7175 038e3415100a Added ini reading/writing for game schemes to the frontend lib Medo <smaxein@googlemail.com> parents: 7173 diff changeset	56	/**
038e3415100a Added ini reading/writing for game schemes to the frontend lib Medo <smaxein@googlemail.com> parents: 7173 diff changeset	57	* Try to receive 4097 bytes. This is the size of the reply the engine sends
038e3415100a Added ini reading/writing for game schemes to the frontend lib Medo <smaxein@googlemail.com> parents: 7173 diff changeset	58	* when successfully queried for map data. The first 4096 bytes are a bit-packed
038e3415100a Added ini reading/writing for game schemes to the frontend lib Medo <smaxein@googlemail.com> parents: 7173 diff changeset	59	* twocolor image of the map (256x128), the last byte is the number of hogs that
038e3415100a Added ini reading/writing for game schemes to the frontend lib Medo <smaxein@googlemail.com> parents: 7173 diff changeset	60	* fit on the map.
038e3415100a Added ini reading/writing for game schemes to the frontend lib Medo <smaxein@googlemail.com> parents: 7173 diff changeset	61	*/
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	62	int flib_ipcbase_recv_map(flib_ipcbase ipc, void data);
7175 038e3415100a Added ini reading/writing for game schemes to the frontend lib Medo <smaxein@googlemail.com> parents: 7173 diff changeset	63
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	64	int flib_ipcbase_send_raw(flib_ipcbase ipc, const void data, size_t len);
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	65
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	* 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	68	* 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	69	*
a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	70	* 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	71	* Returns a negative value on failure.
a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	72	*/
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	73	int flib_ipcbase_send_message(flib_ipcbase ipc, void data, size_t len);
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	74
a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	75	/**
7162 fe76d24a25d7 Demo recording for the frontend library Medo <smaxein@googlemail.com> parents: 7160 diff changeset	76	* Convenience function for sending a 0-delimited string.
fe76d24a25d7 Demo recording for the frontend library Medo <smaxein@googlemail.com> parents: 7160 diff changeset	77	*/
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	78	int flib_ipcbase_send_messagestr(flib_ipcbase ipc, char data);
7162 fe76d24a25d7 Demo recording for the frontend library Medo <smaxein@googlemail.com> parents: 7160 diff changeset	79
fe76d24a25d7 Demo recording for the frontend library Medo <smaxein@googlemail.com> parents: 7160 diff changeset	80	/**
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	81	* Try to accept a connection. Only has an effect in state IPC_LISTENING.
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	82	*/
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	83	void flib_ipcbase_accept(flib_ipcbase *ipc);
7162 fe76d24a25d7 Demo recording for the frontend library Medo <smaxein@googlemail.com> parents: 7160 diff changeset	84
7234 613998625a3c frontlib: Started work on the server connection code Medo <smaxein@googlemail.com> parents: 7224 diff changeset	85	#endif /* IPCBASE_H_ */
7158 a0573014ff4f Further work on the frontend library, restructuring, ... Medo <smaxein@googlemail.com> parents: diff changeset	86

author	Medo <smaxein@googlemail.com>
	Tue, 19 Jun 2012 21:17:05 +0200
changeset 7234	613998625a3c
parent 7224	project_files/frontlib/ipc/ipcconn.h@5143861c83bd
child 7271	5608ac657362
permissions	-rw-r--r--