diff -r 4feced261c68 -r de822cd3df3a project_files/frontlib/ipc/mapconn.h --- a/project_files/frontlib/ipc/mapconn.h Tue Jan 21 22:38:13 2014 +0100 +++ b/project_files/frontlib/ipc/mapconn.h Tue Jan 21 22:43:06 2014 +0100 @@ -1,116 +1,116 @@ -/* - * Hedgewars, a free turn based strategy game - * Copyright (C) 2012 Simeon Maxein - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License - * as published by the Free Software Foundation; either version 2 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - */ - -/** - * Functions for querying a map preview from the engine, which includes both a two-color image - * and the number of hogs this map is suitable for. - * - * The general usage is to first create a mapconn object by calling flib_mapconn_create. - * That will cause the frontlib to listen on a random port which can be queried using - * flib_mapconn_getport(). You should also register your callback functions right at the start - * to ensure you don't miss any callbacks. - * - * Next, start the engine (that part is up to you) with the appropriate command line arguments - * for a map preview request. - * - * In order to allow the mapconn to run, you should regularly call flib_mapconn_tick(), which - * performs network I/O and calls your callbacks if the map has been generated or an error - * has occurred. Once either the onSuccess or onFailure callback is called, you should destroy - * the mapconn and stop calling tick(). - */ - -#ifndef IPC_MAPCONN_H_ -#define IPC_MAPCONN_H_ - -#include "../model/map.h" - -#include - -#define MAPIMAGE_WIDTH 256 -#define MAPIMAGE_HEIGHT 128 -#define MAPIMAGE_BYTES (MAPIMAGE_WIDTH/8*MAPIMAGE_HEIGHT) - -typedef struct _flib_mapconn flib_mapconn; - -/** - * Start a new map rendering connection (mapconn). This means a listening socket - * will be started on a random unused port, waiting for a connection from the - * engine process. Once this connection is established, the required information - * will be sent to the engine, and the reply is read. - * - * The map must be a regular, maze or drawn map - for a preview of a named map, - * use the preview images in the map's directory, and for the hog count read the - * map information (e.g. using flib_mapcfg_read). - * - * No NULL parameters allowed, returns NULL on failure. - * Use flib_mapconn_destroy to free the returned object. - */ -flib_mapconn *flib_mapconn_create(const flib_map *mapdesc); - -/** - * Destroy the mapconn object. Passing NULL is allowed and does nothing. - * flib_mapconn_destroy may be called from inside a callback function. - */ -void flib_mapconn_destroy(flib_mapconn *conn); - -/** - * Returns the port on which the mapconn is listening. Only fails if you - * pass NULL (not allowed), in that case 0 is returned. - */ -int flib_mapconn_getport(flib_mapconn *conn); - -/** - * Set a callback which will receive the rendered map if the rendering succeeds. - * - * Expected callback signature: - * void handleSuccess(void *context, const uint8_t *bitmap, int numHedgehogs) - * - * The context passed to the callback is the same pointer you provided when - * registering the callback. bitmap is a pointer to a buffer of size MAPIMAGE_BYTES - * containing a bit-packed image of size MAPIMAGE_WIDTH * MAPIMAGE_HEIGHT. - * numHedgehogs is the number of hogs that fit on this map. - * - * The bitmap pointer passed to the callback belongs to the caller, - * so it should not be stored elsewhere. Note that it remains valid - * inside the callback method even if flib_mapconn_destroy is called. - */ -void flib_mapconn_onSuccess(flib_mapconn *conn, void (*callback)(void* context, const uint8_t *bitmap, int numHedgehogs), void *context); - -/** - * Set a callback which will receive an error message if rendering fails. - * - * Expected callback signature: - * void handleFailure(void *context, const char *errormessage) - * - * The context passed to the callback is the same pointer you provided when - * registering the callback. - * - * The error message passed to the callback belongs to the caller, - * so it should not be stored elsewhere. Note that it remains valid - * inside the callback method even if flib_mapconn_destroy is called. - */ -void flib_mapconn_onFailure(flib_mapconn *conn, void (*callback)(void* context, const char *errormessage), void *context); - -/** - * Perform I/O operations and call callbacks if something interesting happens. - * Should be called regularly. - */ -void flib_mapconn_tick(flib_mapconn *conn); - -#endif +/* + * Hedgewars, a free turn based strategy game + * Copyright (C) 2012 Simeon Maxein + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + */ + +/** + * Functions for querying a map preview from the engine, which includes both a two-color image + * and the number of hogs this map is suitable for. + * + * The general usage is to first create a mapconn object by calling flib_mapconn_create. + * That will cause the frontlib to listen on a random port which can be queried using + * flib_mapconn_getport(). You should also register your callback functions right at the start + * to ensure you don't miss any callbacks. + * + * Next, start the engine (that part is up to you) with the appropriate command line arguments + * for a map preview request. + * + * In order to allow the mapconn to run, you should regularly call flib_mapconn_tick(), which + * performs network I/O and calls your callbacks if the map has been generated or an error + * has occurred. Once either the onSuccess or onFailure callback is called, you should destroy + * the mapconn and stop calling tick(). + */ + +#ifndef IPC_MAPCONN_H_ +#define IPC_MAPCONN_H_ + +#include "../model/map.h" + +#include + +#define MAPIMAGE_WIDTH 256 +#define MAPIMAGE_HEIGHT 128 +#define MAPIMAGE_BYTES (MAPIMAGE_WIDTH/8*MAPIMAGE_HEIGHT) + +typedef struct _flib_mapconn flib_mapconn; + +/** + * Start a new map rendering connection (mapconn). This means a listening socket + * will be started on a random unused port, waiting for a connection from the + * engine process. Once this connection is established, the required information + * will be sent to the engine, and the reply is read. + * + * The map must be a regular, maze or drawn map - for a preview of a named map, + * use the preview images in the map's directory, and for the hog count read the + * map information (e.g. using flib_mapcfg_read). + * + * No NULL parameters allowed, returns NULL on failure. + * Use flib_mapconn_destroy to free the returned object. + */ +flib_mapconn *flib_mapconn_create(const flib_map *mapdesc); + +/** + * Destroy the mapconn object. Passing NULL is allowed and does nothing. + * flib_mapconn_destroy may be called from inside a callback function. + */ +void flib_mapconn_destroy(flib_mapconn *conn); + +/** + * Returns the port on which the mapconn is listening. Only fails if you + * pass NULL (not allowed), in that case 0 is returned. + */ +int flib_mapconn_getport(flib_mapconn *conn); + +/** + * Set a callback which will receive the rendered map if the rendering succeeds. + * + * Expected callback signature: + * void handleSuccess(void *context, const uint8_t *bitmap, int numHedgehogs) + * + * The context passed to the callback is the same pointer you provided when + * registering the callback. bitmap is a pointer to a buffer of size MAPIMAGE_BYTES + * containing a bit-packed image of size MAPIMAGE_WIDTH * MAPIMAGE_HEIGHT. + * numHedgehogs is the number of hogs that fit on this map. + * + * The bitmap pointer passed to the callback belongs to the caller, + * so it should not be stored elsewhere. Note that it remains valid + * inside the callback method even if flib_mapconn_destroy is called. + */ +void flib_mapconn_onSuccess(flib_mapconn *conn, void (*callback)(void* context, const uint8_t *bitmap, int numHedgehogs), void *context); + +/** + * Set a callback which will receive an error message if rendering fails. + * + * Expected callback signature: + * void handleFailure(void *context, const char *errormessage) + * + * The context passed to the callback is the same pointer you provided when + * registering the callback. + * + * The error message passed to the callback belongs to the caller, + * so it should not be stored elsewhere. Note that it remains valid + * inside the callback method even if flib_mapconn_destroy is called. + */ +void flib_mapconn_onFailure(flib_mapconn *conn, void (*callback)(void* context, const char *errormessage), void *context); + +/** + * Perform I/O operations and call callbacks if something interesting happens. + * Should be called regularly. + */ +void flib_mapconn_tick(flib_mapconn *conn); + +#endif