git.cworth.org Git - ttt/blob - src/ttt-server.h

   1 /* ttt-server.c - tic-tac-toe game server
   2  *
   3  * Copyright © 2005 Carl Worth
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2, or (at your option)
   8  * any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software Foundation,
  17  * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  18  *
  19  * Author: Carl Worth <cworth@cworth.org>
  20  */
  21
  22 #include "ttt.h"
  23 #include "ttt-error.h"
  24
  25 #ifndef _TTT_SERVER_H_
  26 #define _TTT_SERVER_H_
  27
  28 /* Register a new client with the server.
  29  *
  30  * Returns: TTT_ERROR_NONE on success, else TTT_ERROR_INVALIDNAME if client's
  31  * name is not unique.
  32  *
  33  * Locking: The server mutex will be acquired and held throughout the
  34  * execution of this function.
  35  *
  36  * Errors: If an error (such as out-of-memory) occurs, this function
  37  * will not return.
  38  */
  39 ttt_error_t
  40 ttt_server_register_client (ttt_server_t *server, ttt_client_t *client);
  41
  42 /* Un-register a client from the server.
  43  *
  44  * Locking: The server mutex will be acquired and held throughout the
  45  * execution of this function.
  46  */
  47 void
  48 ttt_server_unregister_client (ttt_server_t *server, ttt_client_t *client);
  49
  50 /* Send a message to all connected clients.
  51  *
  52  * Locking: The server mutex will be acquired and held throughout the
  53  * execution of this function. Each client mutex will also be acquired
  54  * for a portion of the execution of this function.
  55  *
  56  * Errors: If an error such as an IO error occurs, this function will
  57  * not return.
  58  */
  59 void
  60 ttt_server_broadcast (ttt_server_t *server, const char *message);
  61
  62
  63 /* Returns the WHO response. The return string is allocated in this
  64  * function and will need to be free'd by the caller.
  65  *
  66  * Locking: The server mutex will be acquired and held throughout the
  67  * execution of this function.
  68  *
  69  * Errors: If an error such as an IO error occurs, this function will
  70  * not return.
  71  */
  72 const char*
  73 ttt_server_who (ttt_server_t *server);
  74
  75 /* Checks to see whether a username exists.
  76  *
  77  * Returns: ttt_server_get_client_from_username(server, username)
  78  *
  79  * Locking: See ttt_server_get_client_from_username
  80  *
  81  * Errors: See ttt_server_get_client_from_username
  82  */
  83 ttt_error_t
  84 ttt_server_verify_username (ttt_server_t *server,
  85                             const char *username);
  86
  87 /* Points *client to the client with the supplied username, else
  88  * leaves *client unhanged.
  89  *
  90  * Returns: TTT_ERROR_NONE, else TTT_ERROR_NO_USER if username not
  91  * found.
  92  *
  93  * Locking: The server mutex will be acquired and held throughout the
  94  * execution of this function.
  95  *
  96  * Errors: If an error such as an IO error occurs, this function will
  97  * not return.
  98  */
  99 ttt_error_t
 100 ttt_server_get_client_from_username (ttt_server_t *server,
 101                                      const char   *username,
 102                                      ttt_client_t **client);
 103
 104 /* Adds an invitation
 105  *
 106  * Locking: The server mutex will be acquired and held throughout the
 107  * execution of this function.
 108  *
 109  * Errors: If an error such as an IO error occurs, this function will
 110  * not return.
 111  */
 112 ttt_error_t
 113 ttt_server_add_invite (ttt_server_t *server,
 114                        ttt_client_t *actor,
 115                        ttt_client_t *invitee);
 116
 117 /* Removes an invitation
 118  *
 119  * Returns: TTT_ERROR_NONE, else TTT_ERROR_NO_INVITE if no invite
 120  * found.
 121  *
 122  * Locking: The server mutex will be acquired and held throughout the
 123  * execution of this function.
 124  *
 125  * Errors: If an error such as an IO error occurs, this function will
 126  * not return.
 127  */
 128 ttt_error_t
 129 ttt_server_remove_invite (ttt_server_t *server,
 130                           ttt_client_t *actor,
 131                           ttt_client_t *invitee);
 132
 133 /* Gets the server hostname.
 134  *
 135  */
 136 const char*
 137 ttt_server_get_host (ttt_server_t *server);
 138
 139 /* Gets the server port
 140  *
 141  */
 142 const char*
 143 ttt_server_get_port (ttt_server_t *server);
 144
 145 #endif /* _TTT_SERVER_H_ */