/
protocol.h
141 lines (120 loc) · 4.09 KB
/
protocol.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
/*
* The Doomsday Engine Project -- libdeng2
*
* Copyright (c) 2009-2013 Jaakko Keränen <jaakko.keranen@iki.fi>
*
* 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, see <http://www.gnu.org/licenses/>.
*/
#ifndef LIBDENG2_PROTOCOL_H
#define LIBDENG2_PROTOCOL_H
#include "../libdeng2.h"
#include <de/Reader>
#include <QList>
/**
* @defgroup protocol Protocol
*
* Classes that define the protocol for network communications.
*
* @ingroup net
*/
namespace de {
class Block;
class CommandPacket;
class Transmitter;
class Packet;
class Record;
class RecordPacket;
class String;
/**
* The protocol is responsible for recognizing an incoming data packet and
* constructing a specialized packet object of the appropriate type.
*
* @ingroup protocol
*/
class DENG2_PUBLIC Protocol
{
public:
/// The response was not success. @ingroup errors
DENG2_ERROR(ResponseError);
/// The response to a command, query, or other message was FAILURE. @ingroup errors
DENG2_SUB_ERROR(ResponseError, FailureError);
/// The response to a command, query, or other message was DENY. @ingroup errors
DENG2_SUB_ERROR(ResponseError, DenyError);
/**
* A constructor function examines a block of data and determines
* whether a specialized Packet can be constructed based on the data.
*
* @param block Block of data.
*
* @return Specialized Packet, or @c NULL.
*/
typedef Packet *(*Constructor)(Block const &);
/// Reply types. @see reply()
enum Reply {
OK, ///< Command performed successfully.
FAILURE, ///< Command failed.
DENY ///< Permission denied. No rights to perform the command.
};
public:
Protocol();
virtual ~Protocol();
/**
* Registers a new constructor function.
*
* @param constructor Constructor.
*/
void define(Constructor constructor);
/**
* Interprets a block of data.
*
* @param block Block of data that should contain a Packet of some type.
*
* @return Specialized Packet, or @c NULL.
*/
Packet *interpret(Block const &block) const;
/*
* Sends a command packet and waits for reply. This is intended for issuing
* synchronous commands that can be responded to immediately.
*
* @param to Transceiver over which to converse.
* @param command Packet to send.
* @param response If not NULL, the reponse packet is returned to caller here.
* Otherwise the response packet is deleted.
*/
//void syncCommand(Transmitter& to, const CommandPacket& command, RecordPacket** response = 0);
/**
* Sends a reply via a transmitter. This is used as a general response to
* commands or any other received messages.
*
* @param to Transmitter where to send the reply.
* @param type Type of reply.
* @param record Optional data to send along the reply. Protocol takes
* ownership of the record.
*/
void reply(Transmitter &to, Reply type = OK, Record *record = 0);
/**
* Sends a reply via a transmitter. This is used as a general response to
* commands or any other received messages.
*
* @param to Transmitter where to send the reply.
* @param type Type of reply.
* @param message Optional message (human readable).
*/
void reply(Transmitter &to, Reply type, String const &message);
private:
typedef QList<Constructor> Constructors;
Constructors _constructors;
};
} // namespace de
#endif /* LIBDENG2_PROTOCOL_H */