project_files/frontlib/ipc/mapconn.h
author koda
Thu, 13 Jun 2013 14:44:28 +0200
changeset 9219 0a4b6bb69f99
parent 7482 d70a5b0d1190
child 10017 de822cd3df3a
permissions -rw-r--r--
bring windows fixes from main repo
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
7314
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
     1
/*
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
     2
 * Hedgewars, a free turn based strategy game
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
     3
 * Copyright (C) 2012 Simeon Maxein <smaxein@googlemail.com>
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
     4
 *
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
     5
 * This program is free software; you can redistribute it and/or
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
     6
 * modify it under the terms of the GNU General Public License
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
     7
 * as published by the Free Software Foundation; either version 2
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
     8
 * of the License, or (at your option) any later version.
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
     9
 *
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
    10
 * This program is distributed in the hope that it will be useful,
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
    11
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
    12
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
    13
 * GNU General Public License for more details.
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
    14
 *
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
    15
 * You should have received a copy of the GNU General Public License
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
    16
 * along with this program; if not, write to the Free Software
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
    17
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
    18
 */
6171f0bad318 frontlib: Fixes and improvements. Added a GPLv2+ license header to all frontlib
Medo <smaxein@googlemail.com>
parents: 7275
diff changeset
    19
7482
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    20
/**
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    21
 * Functions for querying a map preview from the engine, which includes both a two-color image
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    22
 * and the number of hogs this map is suitable for.
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    23
 *
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    24
 * The general usage is to first create a mapconn object by calling flib_mapconn_create.
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    25
 * That will cause the frontlib to listen on a random port which can be queried using
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    26
 * flib_mapconn_getport(). You should also register your callback functions right at the start
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    27
 * to ensure you don't miss any callbacks.
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    28
 *
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    29
 * Next, start the engine (that part is up to you) with the appropriate command line arguments
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    30
 * for a map preview request.
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    31
 *
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    32
 * In order to allow the mapconn to run, you should regularly call flib_mapconn_tick(), which
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    33
 * performs network I/O and calls your callbacks if the map has been generated or an error
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    34
 * has occurred. Once either the onSuccess or onFailure callback is called, you should destroy
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    35
 * the mapconn and stop calling tick().
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    36
 */
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    37
7177
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    38
#ifndef IPC_MAPCONN_H_
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    39
#define IPC_MAPCONN_H_
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    40
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    41
#include "../model/map.h"
7179
f84805e6df03 Implemented game launching API for the frontlib.
Medo <smaxein@googlemail.com>
parents: 7177
diff changeset
    42
7177
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    43
#include <stdint.h>
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    44
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    45
#define MAPIMAGE_WIDTH 256
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    46
#define MAPIMAGE_HEIGHT 128
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    47
#define MAPIMAGE_BYTES (MAPIMAGE_WIDTH/8*MAPIMAGE_HEIGHT)
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    48
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    49
typedef struct _flib_mapconn flib_mapconn;
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    50
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    51
/**
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    52
 * Start a new map rendering connection (mapconn). This means a listening socket
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    53
 * will be started on a random unused port, waiting for a connection from the
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    54
 * engine process. Once this connection is established, the required information
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    55
 * will be sent to the engine, and the reply is read.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    56
 *
7275
15f722e0b96f frontlib: Getting there :) Added commandline client for testing
Medo <smaxein@googlemail.com>
parents: 7271
diff changeset
    57
 * The map must be a regular, maze or drawn map - for a preview of a named map,
15f722e0b96f frontlib: Getting there :) Added commandline client for testing
Medo <smaxein@googlemail.com>
parents: 7271
diff changeset
    58
 * use the preview images in the map's directory, and for the hog count read the
7482
d70a5b0d1190 frontlib improvements:
Medo <smaxein@googlemail.com>
parents: 7314
diff changeset
    59
 * map information (e.g. using flib_mapcfg_read).
7275
15f722e0b96f frontlib: Getting there :) Added commandline client for testing
Medo <smaxein@googlemail.com>
parents: 7271
diff changeset
    60
 *
7177
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    61
 * No NULL parameters allowed, returns NULL on failure.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    62
 * Use flib_mapconn_destroy to free the returned object.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    63
 */
7275
15f722e0b96f frontlib: Getting there :) Added commandline client for testing
Medo <smaxein@googlemail.com>
parents: 7271
diff changeset
    64
flib_mapconn *flib_mapconn_create(const flib_map *mapdesc);
7177
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    65
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    66
/**
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    67
 * Destroy the mapconn object. Passing NULL is allowed and does nothing.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    68
 * flib_mapconn_destroy may be called from inside a callback function.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    69
 */
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    70
void flib_mapconn_destroy(flib_mapconn *conn);
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    71
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    72
/**
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    73
 * Returns the port on which the mapconn is listening. Only fails if you
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    74
 * pass NULL (not allowed), in that case 0 is returned.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    75
 */
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    76
int flib_mapconn_getport(flib_mapconn *conn);
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    77
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    78
/**
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    79
 * Set a callback which will receive the rendered map if the rendering succeeds.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    80
 *
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    81
 * Expected callback signature:
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    82
 * void handleSuccess(void *context, const uint8_t *bitmap, int numHedgehogs)
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    83
 *
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    84
 * The context passed to the callback is the same pointer you provided when
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    85
 * registering the callback. bitmap is a pointer to a buffer of size MAPIMAGE_BYTES
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    86
 * containing a bit-packed image of size MAPIMAGE_WIDTH * MAPIMAGE_HEIGHT.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    87
 * numHedgehogs is the number of hogs that fit on this map.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    88
 *
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    89
 * The bitmap pointer passed to the callback belongs to the caller,
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    90
 * so it should not be stored elsewhere. Note that it remains valid
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    91
 * inside the callback method even if flib_mapconn_destroy is called.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    92
 */
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    93
void flib_mapconn_onSuccess(flib_mapconn *conn, void (*callback)(void* context, const uint8_t *bitmap, int numHedgehogs), void *context);
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    94
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    95
/**
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    96
 * Set a callback which will receive an error message if rendering fails.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    97
 *
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    98
 * Expected callback signature:
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
    99
 * void handleFailure(void *context, const char *errormessage)
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   100
 *
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   101
 * The context passed to the callback is the same pointer you provided when
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   102
 * registering the callback.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   103
 *
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   104
 * The error message passed to the callback belongs to the caller,
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   105
 * so it should not be stored elsewhere. Note that it remains valid
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   106
 * inside the callback method even if flib_mapconn_destroy is called.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   107
 */
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   108
void flib_mapconn_onFailure(flib_mapconn *conn, void (*callback)(void* context, const char *errormessage), void *context);
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   109
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   110
/**
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   111
 * Perform I/O operations and call callbacks if something interesting happens.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   112
 * Should be called regularly.
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   113
 */
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   114
void flib_mapconn_tick(flib_mapconn *conn);
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   115
bf6cf4dd847a Implemented public API for letting the engine render maps
Medo <smaxein@googlemail.com>
parents:
diff changeset
   116
#endif