protocol.h

Go to the documentation of this file.
00001 /*
00002  * protocol.h
00003  *
00004  * Copyright (C) 2007-2009  Thomas A. Vaughan
00005  * All rights reserved.
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  *
00031  * The aesop protocol.  The interface by which the server
00032  * communicates with aesop clients, and vice-versa.
00033  */
00034 
00035 #ifndef AESOP_AESOP_PROTO_PROTOCOL_H__
00036 #define AESOP_AESOP_PROTO_PROTOCOL_H__
00037 
00038 // includes --------------------------------------------------------------------
00039 #include "netlib/netlib.h"
00040 
00041 #include "aesop-base/errors.h"
00042 
00043 
00044 // forward declaration
00045 class Datahash;
00046 
00047 
00048 namespace aesop {
00049 
00050 
00051 
00052 ////////////////////////////////////////////////////////////////////////////////
00053 ///
00054 /// \ingroup aesop_core
00055 /// \defgroup aesop_proto AESOP Network Protocol
00056 ///
00057 ///     This is the base messaging layer for the aesop server.  It has a very
00058 ///     simple message-passing format (datahashes in clear text over the wire),
00059 ///     with simple syntax checking.
00060 ///
00061 ///     This library is intended to be used to easily create aesop-specific
00062 ///     messages.  Use the netlib networking library to create connections, and
00063 ///     send/receive messages over the network.
00064 ///
00065 ///     See the netlib documentation at
00066 ///     http://wavepacket-lib.sourceforge.net/group__netlib.html
00067 ///
00068 /// \b NOTE: like the lower-level netlib networking library, this API is NOT
00069 ///     threadsafe.  Thread synchronization should be handled at a higher level.
00070 ///
00071 ////////////////////////////////////////////////////////////////////////////////
00072 /*@{*/
00073 
00074 
00075 /// these are the default TCP/UDP ports used by the AESOP engine.  These can be
00076 ///     overridden!  If you run a server, you can specify the client and server
00077 ///     ports to be used for your instance.  But in the lack of overrides, these
00078 ///     are the ports that will be used.
00079 /// These particular values were chosen because they appear to be unused
00080 ///     by other programs.
00081 enum eDefaultPorts {
00082         // client-side ports
00083         eDefaultPort_clientUdp          = 20051, ///< client UDP send/receive
00084 
00085         // server-side ports
00086         eDefaultPort_serverUdp          = 20050, ///< server UPD send/receive
00087         eDefaultPort_serverTcp          = 20051, ///< server TCP listening port
00088 
00089         // keep this last
00090         eDefaultPort_Invalid            = 0
00091 };
00092 
00093 
00094 
00095 ////////////////////////////////////////////////////////////////////////////////
00096 //
00097 //      protocol message creation helpers
00098 //
00099 ////////////////////////////////////////////////////////////////////////////////
00100 
00101 smart_ptr<netlib::MessageBuffer> createTcpConnectMessage(
00102                                 IN long token);
00103 
00104 // general notification from server to client of errors
00105 smart_ptr<netlib::MessageBuffer> createNotifyErrorMessage(
00106                                 IN eErrorCode errorCode,
00107                                 IN const char * message);
00108 
00109 smart_ptr<netlib::MessageBuffer> createConversationDialogMessage(
00110                                 IN int localPlayerId,
00111                                 IN const char * conversationGuid,
00112                                 IN int dialogId,
00113                                 IN const char * dialogData);
00114 
00115 smart_ptr<netlib::MessageBuffer> createConversationReplyMessage(
00116                                 IN int localPlayerId,
00117                                 IN const char * conversationGuid,
00118                                 IN int dialogId,
00119                                 IN const char * reply);
00120 
00121 smart_ptr<netlib::MessageBuffer> createRefreshConversationMessage(
00122                                 IN int localPlayerId,
00123                                 IN const char * conversationGuid);
00124 
00125 smart_ptr<netlib::MessageBuffer> createTerminateConversationMessage(
00126                                 IN int localPlayerId,
00127                                 IN const char * conversationGuid);
00128 
00129 
00130 smart_ptr<netlib::MessageBuffer> createNewGameMessage(
00131                                 IN int localPlayerId);
00132 
00133 
00134 };      // aesop namespace
00135 
00136 
00137 
00138 #endif  // AESOP_AESOP_PROTO_PROTOCOL_H__
00139