Game Name Search Protocol Specification
Version 10.15.2005.0
October 15, 2005
Chris Haag
Gamieon, Inc.
This document describes the Game Name Search (GNS) protocol, its intended
purpose, architecture, and structure.
This is a preliminary draft of the GNS protocol. It is likely that several revised drafts will appear in succession over a short period of time. This document may be freely distributed and referenced for the purpose of product development with no restriction.
The latest GNS protocol specification may be accessed from http://www.gamieon.com/gns/gnsProtocol.htm.
Contents
1. INTRODUCTION
The purpose of the Game Name Search protocol is to describe the implementation parameters of systems which provide the following mechanisms for network-based applications: Application name to IP address resolution, hosted application searching, content management and distribution, chat room communications serving, error reporting, and server management. These tasks are accomplished through exchanges of information between GNS clients and GNS servers.
1.1 CAPABILITIES
1.2 LOGICAL ARCHITECTURE
The GNS architecture in its simplest form in the context of video games is this: Servers hold a list of hosted video games, a chat room, and generic content. Clients connect to servers to get the list of hosted video games, connect to chat rooms to talk to other players either inside or outside of the game, send error reports, and downloads product updates and game add-ons.
In its complex form where numerous different products exist in a topology, multiple logical servers that are maintained in a tree-like hierarchy champion the management of those products individually. At the root of the tree is the main server, whose job is to forward client requests to subordinates. Those subordinates in turn either forward them to their subordinates, or process those requests and respond to the clients.
Individuals familiar with the DNS protocol (RFC 1035) may think of GNS as a similar architecture in some respects. Some of the outstanding differences are that GNS leaf nodes may represent hosted video games that are not meant to do actual name translations, parent nodes provide multimedia services (like content hosting and chat rooms) in addition to name translations, and leaf nodes will appear and disappear more rapidly because, with the exception of dedicated servers, hosted applications usually don't last more than a few hours.
1.3 PHYSICAL ARCHITECTURE
A logical GNS server may actually consist of a physical cluster of GNS server instances. The physical architecture is of much greater complexity than the logical architecture because the implementation of ideas like load balancing and content sharing are necessary for a functional system. The GNS protocol defines packets that allow servers to exploit those abilities. Details may be found in section 7 of this document.
2 TOPOLOGY
2.1 ZONES
GNS servers logically exist in a tree-like graphical hierarchy. The hierarchy that describes the entire logical GNS universe, as well as a hierarchy that denotes a subset of that universe, is referred to as a zone. This organization reflects a command structure where each logical server has a unique role in delegation and the exchange of information. For example, in order to find people playing "WidgetFighter v2.0" using the mega expansion pack, the root server instructs the client to access the WidgetFighter server. In turn, the WidgetFighter server informs the client to access the version 2.0 server, which then directs the client to the logical mega expansion pack server. The logical mega expansion pack server then returns its game list to the client. The hierarchial order is shown below in the form of a single branch in a zone:
"\" (Root server)
+"WidgetFighter" (Super Widget Fighter Server)
++"2_0" (Version 2.0)
+++"MegaExpPack" (Mega expansion pack)
++++"John's game"
++++"Ted' game"
++++"Albert's game"
At the top level of any zone is the root server, whose goal is to ensure a client request is either answered, or forwarded to the correct subordinate server. The more subordinates there are beneath a root server, the more likely the server will be dedicating its resources to delegating requests to those subordinates. Subordinates themselves act as root servers of their own zones. The leaf subordinates at the bottom of zone hierarchies (shown in blue) represent actual instances of the application. The role of these nodes is to notify their parent servers of their existances, and properties of those instances (such as player count and scoring). When a GNS server creates an outgoing communication to another GNS server, that server is objectively treated as a GNS client by the listener.
2.2 NAMING CONVENTION
The name of a zone, called the FQGN (or Fully Qualified Game Name) consists of the name followed by the names of father and grandfather zones in order of their level, all separated by a period symbol. Zone names must be treated with case insensitivity, and there is no defined length for a FQGN. In the case mentioned in section 2.1, the name of the mega expansion pack server zone is:
MegaExpPack.2_0.WidgetFighter
It is acceptable to have a period in a name, provided that the name contains single or double-quotations. It is acceptable for names to have single or double-quotations as well, but to differentiate them from string encapsulation markers, they need to appear twice in a row. Zone names may also have a trailing period at the end. Here are some examples of acceptable and unacceptable names:
Acceptable
.
megaexppack.2_0.widgetfighter
megaexppack.2_0.widgetfighter.
megaexppack.'2.0'.widgetfighter
megaexppack."2.0".widgetfighter
"..:: Jet's game::...".2_0.widgetfighter
"""House of explosions""".2_0.'widgetfighter'
Acceptable but discouraged
"megaexppack.2_0.widgetfighter" (this has no
hierarchial organization)
Unacceptable
megaexppack.2_0.widgetfighter'
"megaexppack.2_0.widgetfighter
"megaexp"pack".2_0.widgetfighter
2.3 AUTHORITIES
An authority is an entity responsible in executing or assisting the processing of a request. There are two kinds of GNS authorities: Primary and secondary.
2.3.1 PRIMARY AUTHORITIES
Primary authorities process requests and respond to clients. Primary authorities only redirect clients to secondary authorities in the event they consider themselves to be overloaded with work.
2.3.2 SECONDARY AUTHORITIES
Secondary authorities have several roles: Maintaining a copy of information provided by a primary authority, processing client requests using that cached information, and routing clients to other secondary authorities and primary authorities.
2.3.3 TASKS
A given GNS server usually has several authorities that pertain to different kinds of requests:
2.3.3.1 ZONE
Zone authorities are responsible for logical zone topology maintenance. Requests for zone authorities are usually made to add, remove, and change the properties of zone nodes.
2.3.3.2 CONTENT
Content authorities are responsible for maintaining content stored on GNS servers. Requests for content authorities are usually made to create, overwrite, move, and delete files, folders and other data stores in the content repository.
2.3.3.3 CHAT
Chat authorities are effectively chat servers. All chat-related activity is done through chat authorities, including logging into and out of chat servers, and engaging in conversation.
2.3.3.4 MANAGEMENT
Management authorities are responsible for physical zone topology maintenance. Requests made through this authority affect the logical roles of every physical server for the purpose of maximizing the collective efficiency of the logical node. For example, if two physical servers are online using cable modems for Internet-based packet exchanges; and one of them is moved to a site with a T1, then the servers can use methods involving the exchange of management packets to ultimately reassign some of the roles of the server behind the cable modem over to the T1 server.
2.3.3.5 PING
Ping authorities have the simple responsibility of handling non-ICMP ping requests. When a ping packet is received, a response with the same data payload is transmitted back to the sender.
2.3.3.6 CONSOLE
Console authorities are responsible for verbose exchanges between GNS server and clients. GNS Servers may allow remote sites access through command shells for server configuration.
2.3.3.7 ERROR REPORT
Error report authorities are responsible for managing bug reporting. Reports are accepted from clients, stored, and reported to either local or remote GNS server administrators.
2.3.4 TIME TO LIVE
Part of what makes an authority an authority is the fact it has up to date information. Primary authorities always have the most recent information available and are updated realtime, while secondary authorities tend to have information that is a little older, and update in much larger intervals than primary authorities. The amount of time that passes before information is considered "out of date" for an authority is its Time To Live. Once the time to live, or TTL, has expired; the authority must either get information from the primary authority, get it from a secondary authority with a reasonable TTL remaining, or bow out of being an authority.
2.4 THE COMMUNICATION PROCESS
The following pseudocode describes all possible transactions between a client and a server:
while (client: has_no_response and has_authorities_to_try) {
client: send_request_to_next_authority_server();
server: get_request();
server: if (can_process_request()) {
server:
send_response_to_client();
client: get_response()
}
else
{
server: send_all_authorities_that_client_hasnt_talked_to();
client:
get_authority_list();
}
}
This not only applies to cases where the client is a video game searching for
game listings, but also for where the client is a secondary authority trying to
get information from a primary authority, or another secondary authority with
less outdated information.
3. ADMINISTRATION AND AUTHENTICATION
3.1 USERS
A user is synonymous with the identity of a client that connects to a logical GNS server. Given the identity, the server can determine what the client can and cannot do on the server. By default, when a client connects to, or makes first contact with a GNS server, it is assigned the "anonymous" user identity with limited privileges. Beyond this point, the client may log onto the server with a different pre-defined identity that grants them additional privileges on the server. Technical details of how to log into a server can be found in section 10.3.2. For security reasons, the login process may be protected with encryption.
A typical user is the administrator of a logical GNS zone. For example, a GNS administrator working with an independent developer writing a game called "VGARunner2006" can create a user for that developer named 'VGARunner2006admin' with full VGARunner2006 zone permissions, and another user named 'VGARunner2006user' with permissions to create and remove VGARunner2006 children. The developer would then program his client to log in as 'VGARunner2006user' each time it wants to host or unhost a game. This way, no other player for any other game in existence could create or destroy elements in that zone.
Every user has a home zone, and must log into their home zone. Users have no authority outside their home zone, but authority is inherited in all child zones.
3.1.1 PROPERTIES
Users have the following properties:
3.1.2 THE ANONYMOUS USER
As stated earlier, when a client makes first contact with a GNS server by default, it is assigned the "anonymous" user identity with limited privilieges. In a typical server implementation, anonymous users can get application and application property listings for various games. A GNS server must have an anonymous user, but it is not required to have any permissions of any kind.
3.1.3 THE GNSROOT USER
The "gnsroot" user has full permissions for universal maintenance of the GNS server, and they can never be taken away. In a typical implementation, the gnsroot user logs in remotely on an encrypted connection for maintenance, or does maintenace at the implementation's local console. A GNS server is required to have a gnsroot user, but it is not required to have remote access.
3.1.4 TTL (Time to Live)
When a client is connected to the server as an explicit user, there is a finite amount of time before the user's session becomes invalid, and the client must reidentify itself. This is specified in the server's response to the client (Section 10.3.2).
3.1.5 TCP VS. UDP
Because TCP is connection oriented, if the connection is broken between the server and the client, the TTL will automatically expire, and the user must reauthenticate with the server at the next logon. Logins are also possible over the UDP protocol, but the TTL must be a pratically small value. Otherwise, packets coming in from the source IP address and port could actually come from another client who should not have the active login privileges.
3.2 GROUPS
Groups make it possible to manage the privileges of several users without having to do so one user at a time. A user can be assigned to one or more groups. Lets say a GNS server administrator works with five developers writing a game called "WidgetBomber4.0". The administrator would create a group called WidgetBomberAdmins, and create five users that are associated with that group. The membership of those users in the group give them full privileges to the WidgetBomber4.0 zone. The administrator would; however, still have to create a WidgetBomberPlayer account with privileges to host and unhost games in the zone.
Lets take the example further: Say the developers package the product, and everyone gets a CD Key. They want to associate those CD Keys with hosted games. So, the GNS server administrator creates a new group called WidgetBomberPlayers, and configures the server to authenticate the CD Keys by writing a special plug-in. Players will host their games after logging in with their username, password, and CD-Keys; all of those players being in the WidgetBomberPlayers group. The GNS server will not only check the group permissions to verify the users can host and unhost games, but check for duplicate CD-Keys and deny hosting access to players who appear to host more than once at a time.
3.2.1 PROPERTIES
Groups have the following properties:
3.3 PERMISSIONS
The permissions schema of GNS is a two-dimensional lookup of stores and consumers. A store is a repository of information, such as a zone, an authority or a content file. A consumer is an interactive entity that accesses stores; this pertains to users and groups. A permission defines how a specific consumer can interact with a specific store. Just because a user can host a game in one zone doesn't mean the user can create it in another zone. Likewise, just because someone in a group can change the "CurrentMission" property of a zone leaf which represents a game, doesn't mean that person can change the "MaxPlayers" value. The granularity will always be per-store per-consumer.
3.3.1 ENTITY PERMISSION PERMUTATION TABLE
|
Zone |
Authority |
Zone Property |
Content File |
Chat Channel |
Console |
Management |
Error Reporting |
|
|
Login |
The consumer can log onto a GNS server with the specified home zone. |
n/a |
n/a |
n/a |
The consumer can log into the chat channel. |
The consumer can create and log into a console. |
n/a |
n/a |
|
Read |
The consumer can get the list of subordinate zones. |
The consumer can get information about the authority. |
The consumer can read the zone property. |
The consumer can download the content file. |
The consumer can read messages sent to the chat channel. |
The consumer can read console output. |
n/a |
The consumer can download submitted reports |
|
Write |
n/a |
The consumer can modify the authority. |
The consumer can change the zone property. |
The consumer can change the content file. |
The consumer can write messages to the chat channel. |
The consumer can write messages to the console. |
The consumer can assign users to groups |
The consumer can submit error reports |
|
Create |
The consumer can create a child zone from a factory (See section 3.3.2) |
The consumer can create an authority for the zone from a factory (See section 3.3.2) |
The consumer can create a zone property from a factory (See section 3.3.2)
|
The consumer can create a content file from a factory (See section 3.3.2)
|
The consumer can create a chat channel from a factory (See section 3.3.2)
|
n/a
|
The consumer can create users and groups |
n/a |
|
Destroy |
The consumer can destroy the zone and all its subordinates. |
The consumer can delete the authority. |
The consumer can delete the zone property. |
The consumer can delete the content file. |
The consumer can delete the chat channel. |
n/a |
The consumer can destroy users and groups |
n/a |
|
Grant |
The consumer can grant other consumers the same zone permissions that consumer has. |
The consumer can grant other consumers the same authority permissions... |
The consumer...same zone property permissions... |
The consumer...same content file permissions... |
The consumer...same chat channel permissions... |
The consumer...same console permissions... |
n/a |
n/a |
|
Deny |
The consumer can deny other consumers the same permissions that consumer has. |
The consumer...same authority permissions.. |
The consumer...same zone property permissions... |
The consumer...same content file permissions... |
The consumer...same chat channel permissions... |
The consumer...same console permissions... |
n/a |
n/a |
3.3.2 STORE FACTORIES
The permissions structure is fairly straightforward unless you are dealing with the CREATE permission. A consumer can only have a create permission for a "Store Factory". A store factory is an object that creates stores and defines the default permissions of those stores for the consumer that created them. Store factories always exist in specific contexts. For example, a specific zone owns one factory to create sibling zones, one to create properties, and one to create authorities under that zone. A content authority owns a factory to create content files under that authority. Store factories can only be associated with create permissions, and nothing else.
3.3.3 TOKENS
The purpose of a token is to authenticate a user when performing operations that do not require a persistent connection or flow of data with a GNS server. Token granularity is per-zone; only one consumer can own a zone at a time. The most common example of this is the act of hosting a game. After the initial host, the client may connect or send a packet to the GNS server every so often. Without a token, anyone that knows just the client login information can connect to the GNS server claiming to be the same client. The permission checking process for performing a zone operation is twofold:
3.4 ENCRYPTION
Encryption is not mandatory for any operation, but it is encouraged for sensitive operations like logins. The first packet that should be sent in an encryption stream is the GNS_PURPOSE_ENCRYPTION packet described in section 10.3.1.
3.4.1 PROTOCOLS
The initial encryption negotation follows the Diffie-Hellman key exchange algorithm, found at http://www.codeproject.com/cpp/DiffieHellmanExample.asp. After the encryption key is determined, the block cipher algorithm, found at http://www.codeproject.com/cpp/aes.asp, must be used in data exchanges between clients and servers. More details can be found in section 10.3.1.
3.4.2 TTL
After the encryption key has been negotiated, it will last for a finite amount of time before it must be renegotiated. This TTL, or "time to live," is specified in a GNS_PURPOSE_ENCRYPTION response packet described in section 10.3.1.
4. GAME MANAGEMENT
Hosted video games are themselves logical GNS servers with few capabilities. A game is not required to be aware of the complete zone topology; at a minimum it should be aware of its parent node.
4.1 GAME HOSTING
This describes the life cycle of a game from the time it has hosted to the time it is unhosted. Details, such as when to connect, or disconnect to the server, encryption, and logging in are all optional.
4.2 GAME SEARCHING
To find existing games, the following sequence is followed. Details, such as when to connect or disconnect to the server, encryption, and logging in are all optional:
5 CHAT ROOM MANAGEMENT
Chat servers are simply authorities that are delegated the task of GNS_TASK_CHAT. You can have only one chat server in a zone. Because hosted games themselves are zone owners, they may also have chat room authorities that apply to in-game and out-of-game chatting.
5.1 CHAT CHANNELS
A chat channel describes a network of individual chat users who wish to communicate with each other. Chat users must explicitly enter and leave channels in order to participate in those networks. GNS permissions operate per-channel. Standard users have read and write access to the channel. Channel operators have Grant and Deny permissions for the chat channel as well, which can affect all others logged into the same channels.
5.2 CHAT USERS
A GNS session can only have one active chat user at a time per chat server. A chat user can; however, exist in multiple channels at a time. In addition to the Authority and Chat Channel permissions outlined in section 3.3.1, GNS permissions apply such that a chat user is both a store and a consumer. This way, the server can control chat user preferences where users wish to ignore each other, or only write to a group of users in a channel at once.
5.3 PUBLIC MESSAGING
A GNS client must follow these steps to engage in a chat channel conversation. Details, such as when to connect or disconnect to the server, encryption, and logging in are all optional:
5.4 PRIVATE MESSAGING
A client can send a private chat message to another client by sending a GNS_PURPOSE_PRIVCHATMSG packet (Section 10.3.15). The client does not have to be in a chat room to do this, and neither does the recipient. The recipient, however, can deny that client write permission to the client if the recipient wants to ignore the client.
6. CONTENT MANAGEMENT
GNS servers may have a single authority that acts as a content server that allows access to the following data:
These can be contained in files or databases, or any medium the server chooses. The media format is defined in content request packets (Sections 10.3.16, 10.3.17) in the prefix of the filename. A prefix of "file:\\" indicates the path to a file or folder. Other prefixes can be defined by GNS servers to mean different things, such as access to a SQL-based server.
GNS servers can allow clients to upload and download content with per-file granularity as dictated by GNS permissions (Section 3.3.1).
The GNS protocol supports the following:
6.1 CONTENT DOWNLOADS
Clients must have read access to the files they intend to download. The client must follow the steps listed below. Details, such as when to connect or disconnect to the server, encryption, and logging in are all optional:
6.2 CONTENT UPLOADS
Clients must have write access to the files they intend to change, and create acess for those they wish to upload. The client must follow the steps listed below. Details, such as when to connect or disconnect to the server, encryption, and logging in are all optional:
6.3 CATALOGGING
Catalogging in the context of a GNS server is where a single comma-delimited Unicode string consisting of directory, and optionally subdirectory information is generated. The string can include one or more of the following:
The string is sent in response to GNS_PURPOSE_CONTENT_CATALOG requests to allow clients to easily determine which files to download in various operations, such as product updates.
7. MULTI-SERVER MAINTENANCE
In a paradigm where a logical GNS server topology consists of numerous physical servers, there should be a way for those servers to coordinate in such a way that a responsive and robust GNS system can exist. To accomplish this, physics servers must track performance benchmarks and relay the results to a designated manager server so it can alter the authority configurations of all servers involved.
7.1 METRICS
An implementation should track the minimum, maximum, and average values of the following:
7.2 REPORTING
Reporting is done when worker servers report their metrics to an administrative server through sending zone properties that contain the metrics. This is best described in an imaginary test case:
Lets assume the Orlando and Sarasota servers are on the same network. It's clear in this example that Sarasota needs to pitch in more. This brings us to the next action: resolution.
7.3 RESOLUTION
If the administrative server calculates that CPU, network, or disk I/O traffic is unbalanced, and that the logical server could operate more efficiently by correcting the imbalance, then it should formulate a way to redistribute the work and put that formulation into effect.
7.3.1 ROLE RE-ASSIGNMENTS
An administrative server can send Set Authority (10.3.4) and Remove Authority (10.3.5) packets to change subordinate server roles. Those servers can then change their authority redirection tables accordingly so that clients are forwarded to different physical servers. This propogation effort should be immediate.
7.3.2 PACKET REDIRECTION
Another tactic to balance traffic is redirecting packets through the use of hardware routers. A GNS server being overburdened with work could change the logic of the hardware router to forward every Nth packet directed to a specific port to go another IP address. That would have to be done through a specialized implementation of the GNS server.
8. ERROR REPORTING
In the unfortunate event that an application crashes, the most beneficial action for both the developer and the user is for the user to relay information to the developer that helps them determine the problem, and resolve it.
8.1 ERROR REPORT PAYLOAD FORMAT
Because the needs of most applications are different from each other, there is no standard format for the data payload of error reporting packets. At a minimum, a snapshot of the application's register state, call stack, and list of loaded module dependencies would be very helpful to the developer. A developer should also weigh the value of allowing users to submit their e-mail address or project membership identification in the event that communication with the user could also assist in problem resolution.
8.2. ERROR REPORT PREPARATION
As soon as an unhandled or fatal exception is reported in an application, the flow of control should assume the application is permanently unstable, and only a bare minimum of code should be executed before complete shutdown. The following code execution should take place:
1. Defunc application gathers error report information
2. Defunc application saves it to disk, or other storage medium for a secondary
application to access
3. Defunc application launches secondary application
4. Defunc application terminates
5. Secondary application gathers error information created from defunc
application
6. Secondary application sends error information to GNS server
7. Secondary application shuts down after successful error report submission.
8.3 ERROR REPORT SUBMISSION
Submitting an error report to a GNS server is a multi-step process:
1. Client connects to the server
2. Depending on the security levels of the server, the client will exchange
GNS_PURPOSE_ENCRYPTION or GNS_PURPOSE_LOGIN packets with the server first.
3. The client sends a GNS_PURPOSE_BUG_REPORT packet to the server.
4. The server responds with an empty GNS_PURPOSE_BUG_REPORT packet confirming
reception and storage of the error report.
9. CONSOLE COMMUNICATIONS
GNS servers can be actively configured at the local console through an exchange of command-line instructions. They may also be configured from a remote client with the proper credentials.
9.1. PACKET PAYLOAD FORMAT
Both command requests and responses consist of a variant object. This variant may contain the actual text entered by the user, and the textual response of the server; or a special proprietary data format which exists in the variant as binary data.
9.2. PERMISSIONS
A remote client must have LOGIN permission to create a console, and READ and WRITE permissions to exchange information with it. Actual console commands have their own permissions. For example, to create a new authority from a console, the user must have the same privileges they would if they were to send a GNS_PURPOSE_SET_AUTHORITY packet.
9.3 COMMANDS
Command names are treated case-insenitive on GNS servers.
9.3.1 AUTH (Set Authority)
| Syntax |
auth a b c d e f g h i j k tasks a is the unique numeric ID of the authority |
| Permissions |
Any user with CREATE permissions for ZONE and AUTHORITY factories if the
authority does not exist, or WRITE permissions to the ZONE and AUTHORITY if
they already do exist. |
| Description | Creates or sets an authority for a zone. This is used for logical GNS
topology configuring, and for hosting games. |
9.3.2 AUTHGROUPPERM (Authority Group Permissions)
| Syntax |
authgroupperm a b c |
| Permissions | GRANT permission for the authority |
| Description | Assign authority permissions to all members of a user group |
9.3.3 CATALOG (Content folder catalog)
| Syntax |
catalog a b c |
| Permissions | Must be the local console user or the gnsroot user to perform |
| Description | Creates a comma-delimited string of directory information pertaining to the
default content folder of the specified authority. This string is sent to GNS
clients that request a GNS_PURPOSE_CONTENT_CATALOG packet. |
9.3.4 GROUP (Group)
| Syntax |
group a |
| Permissions | Must have CREATE permissions for the server's home zone's management authority. |
| Description | Creates a new permissions group. |
9.3.5 GROUPMEMBER (Group membership designation)
| Syntax |
groupmember a b |
| Permissions | Must have WRITE and GRANT permissions for the server's home zone's management
authority. |
| Description | Adds a user to a group. |
9.3.6 HOME (Logical server home zone)
| Syntax |
home a |
| Permissions | This can only be done from the local console. |
| Description | Designates the home zone of the GNS server. This must only be executed once,
and be the first command executed during server initialization. |
9.3.7 INTERFACE (Connect to a plug-in console)
| Syntax |
interface a |
| Permissions | Must have LOGIN access to the plug-in object. |
| Description | Connect to a plug-in from a console. All further console commands are routed to
the plug-in directly. |
| Syntax |
listen a |
| Permissions | This can only be done from the local console or by the gnsroot user. |
| Description | Listens for connections on an authority that is not in the server's
logical home zone. |
9.3.9 LOADPLUGIN (Loads a third-party plug-in)
| Syntax |
loadplugin a b |
| Permissions | This can only be done from the local console. |
| Description | Loads a plug-in from disk. This should be executed only upon server startup. |
9.3.10 PLUGINGROUPPERM (Plug-in group permissions)
| Syntax |
plugingroupperm a b c |
| Permissions | Must have GRANT permissions for the plug-in. |
| Description | Assigns plug-in permissions to a user group. |
9.3.11 PROPNUMBER (Set property number)
| Syntax |
propnumber a b |
| Permissions | Must have WRITE permissions for the management authority of the logical home
zone of the server. |
| Description | Assigns a generic global property number to use totally at the application's
discretion. |
9.3.12 PROPSTRING (Set property string)
| Syntax |
propstring a b |
| Permissions | Must have WRITE permissions for the management authority of the logical home
zone of the server. |
| Description | Assigns a generic global property string to use totally at the application's
discretion. |
9.3.13 USER (Creates a new user)
| Syntax |
user a b c d e f |
| Permissions | Must have CREATE permissions for the management authority of the logical home
zone of the server. |
| Description | Creates a new user to be recognized by the GNS server's logical home zone
and all its children. |
9.3.14 ZONEGROUPPERM (Zone group permission)
| Syntax |
zonegroupperm a b c |
| Permissions | Must have GRANT permissions for the zone. |
| Description | Assigns zone permissions to a user group. |
9.4 THIRD-PARTY PLUG-IN'S
GNS servers may integrate with third party software modules, each having their own console. In order to remotely access those modules, clients connected to GNS consoles may use the interface command to create a pass-through to the console of a specific module. A client may then communicate with the plug-in console until the exit command is used to return to the GNS server console.
10. GNS PACKET FORMAT
10.1 GNS PACKET HEADER STRUCTURE
|
0x474E5300 (32 bits) |
|
Size (32 bits) |
|
Type (8 bits) |
|
Purpose (24 bits) |
|
FQGN (Unicode string of n > 0 bits) |
|
Data (q >= 0 bits) |
10.1.1 - Identifier - (32 bits) 0x474E5300 spells out 'G' 'N'
'S' '\0'. The last byte is the packet structure version, which is currently
version 0.
10.1.2 - Size - (32 bits) The size of the complete packet, in
bytes. This is the combined size of both the header and data content of the
record.
10.1.3 - Type- (8 bits) The type of record (Request, response, authority and error). Please refer to section 10.2 for details.
10.1.4 - Purpose - (24 bits) The purpose of the record. See section 2.2 for the purpose reference.
10.1.5 - FQGN - The Fully Qualified Game Name of the record in the form of a zero-terminated 16-bit Unicode string. If a record has no name, you must still have a wide character null terminator. Some FQGN's, depending on the purpose, may be wildcards. If part of a FQGN is in single or double-quotes, it is treated as a string literal. Here are some example formats for the FQGN:
jimsgame.superfighter3004
'!!! ... Jim''s ""Game"" ... !!!'."v2.05".superfighter3004
*.'v2.05'.mygame
10.1.6 - Data - The data of the record. The type of data is defined by the header's type and purpose.
10.2. GNS PACKET TYPES
Packet types give context to purposes. GNS packet types can be one of four different values.
10.2.1. 0001 - REQUEST
A request value is used when a client is requesting information from a server. Packets with the Request type usually require a Response packet in return. In some cases, an Authority or Error packet is returned, instead.
10.2.2 0002 - RESPONSE
A Response packet is either sent with regards to a Request packet, or, as a notification from a server to a client (such as a chat user leaving a chat room).
10.2.3 0003 - AUTHORITY
An Authority packet is sent if the server is either unwilling or unable to respond to a request, and relies on the client to get the information elsewhere. All Authority packets contain the same data payload that contains information which directs the client to another GNS server:
|
Address Type (8 bits): This describes the address format. This can be one of the following values: 0 - 32-bit IPv4 address |
| Address data (n bits) |
An authority packet may contain a contiguous array of these values.
10.2.4 0004 - ERROR
Error packets are sent in place of response packets if a Request packet was malformed, or if the server was unable to process the request. All Error packets contain the same data:
| Error code (32 bits) - The error code (Refer to section 5 for details). |
| Error message (optional n bits) - A zero-terminated unicode string that describes the conditions under which the error occured |
| Additional data (optional q bits) - Generic data that gives further error information. |
The error code field is required and is standardized by the GNS protocol documentation. The error message and additional data fields are optional and for use by customized GNS implementations.
10.3 GNS PACKET PURPOSES
Unless otherwise designated, every request sent to a server must be answered with a response packet. The content of each kind of packet is listed below. The packet having the ID of 0 is the GNS_PURPOSE_RESERVED packet and is currently not used.
10.3.1 GNS_PURPOSE_ENCRYPTION
| ID | 0001 |
| Name | Encryption stream negotiation |
| Task | (n/a) |
| FQGN | Unused |
| Request Data | |
| Response Data | |
| Error Codes | |
| Description | This packet is used in negotiating a secure encrypted connection between the client and the server. Upon successful negotiation, all data sent in all successive records between the server and the client must be encrypted and utilizing the key until the TTL expires. |
10.3.2 GNS_PURPOSE_LOGIN
| ID | 0002 | |||
| Name | Login | |||
| Task | (n/a) | |||
| FQGN | The intended home zone of the login | |||
| Request Data |
|
|||
| Response Data |
|
|||
| Error Codes |
GNS_ERR_ZONE_DOES_NOT_EXIST - The home zone does not exist GNS_ERR_USER_DOES_NOT_EXIST - The specified user does not exist in the context of the specified home zone GNS_ERR_ACCESS_DENIED - The specified user does not have access to log into the zone |
|||
| Description |
This packet is used in negotiating a login between the GNS server and client. If a login is granted, the client may be given additional privileges, and thus able to utilize more functionality on the GNS server. You should consider exchanging encryption packets with the server before sending a login request. Some examples of login l/p's:
|
10.3.3 GNS_PURPOSE_LOGOUT
| ID | 0003 |
| Name | Logout |
| Task | (n/a) |
| FQGN | The home zone of the original login |
| Request Data | <No Data> |
| Response Data | <A response is required, but there is no data> |
| Error Codes | GNS_ERR_OPERATION_NOT_IN_PROGRESS - The connection was never logged in |
| Description | This packet is used to log out a client who logged in earlier. |
10.3.4 GNS_PURPOSE_SETAUTHORITY
| ID | 0004 | ||||||||||
| Name | Set Authority | ||||||||||
| Task | GNS_TASK_ZONE | ||||||||||
| FQGN | The FQGN of the zone containing the authority | ||||||||||
| Request Data |
|
||||||||||
| Response Data |
|
||||||||||
| Error Codes |
GNS_ERR_ACCESS_DENIED - The client is not logged in as a user who has access to perform this operation. GNS_ERR_INVALID_TOKEN - The token parameter was invalid |
||||||||||
| Description |
This packet is used to create, alter, or remove the authority of a GNS zone. In the context of game hosting, a hosted game exists as a zone with no children of its own. The FQGN should be in the format <name of the game>.<name of the game host zone>. For example, if your game name is "TedsGame" and the game itself is called "SuperWidgetFighter", the FQGN would look something like TedsGame.SuperWidgetFighter. If the zone that represents the hosted game does not exist, it is created, and the owner of the zone will be the client's login user, even if it's Anonymous. The owner cannot be changed through a GNS_PURPOSE_SETAUTHORITY packet. A security authentication token exists in the context of a zone, and is assigned to the client if a new zone is created as a result of a Set Authority packet. This gives the opportunity for the client to identify itself as the owner of the zone, and is required for successive GNS_TASK_ZONE operations. The counter that tracks how long the authority expires by it's time to live is reset any time this packet is sent. |
10.3.5 GNS_PURPOSE_RENEWAUTHORITY
| ID | 0005 | |||
| Name | Renew Authority | |||
| Task | GNS_TASK_ZONE | |||
| FQGN | The FQGN of the zone containing the authority | |||
| Request Data |
|
|||
| Response Data |
|
|||
| Error Codes |
GNS_ERR_ZONE_DOES_NOT_EXIST - The home zone does not exist GNS_ERR_ACCESS_DENIED - The specified user does not have access to log into the
zone |
|||
| Description |
This packet is used to reset the counter that determines when an authority has reached its TTL. The tasks define which authorities to reset the counters of, and unless the description field is an empty string, the description of the authority will also be updated. |
10.3.6 GNS_PURPOSE_DELETEAUTHORITY
| ID | 0006 | |||
| Name | Delete Authority | |||
| Task | GNS_TASK_ZONE | |||
| FQGN | The FQGN of the zone containing the authority | |||
| Request Data |
|
|||
| Response Data |
|
|||
| Error Codes |
GNS_ERR_ZONE_DOES_NOT_EXIST - The home zone does not exist GNS_ERR_ACCESS_DENIED - The specified user does not have access to log into the
zone |
|||
| Description |
This packet is used to delete all authorities whose tasks match the flags parameter of the packet. If all the authorities of a zone are deleted, the zone will still exist. |
10.3.7 GNS_PURPOSE_DELETEZONE
| ID | 0007 | |||
| Name | Delete Zone | |||
| Task | GNS_TASK_ZONE | |||
| FQGN | The FQGN of the zone | |||
| Request Data |
|
|||
| Response Data |
|
|||
| Error Codes |
GNS_ERR_ZONE_DOES_NOT_EXIST - The home zone does not exist GNS_ERR_ACCESS_DENIED - The specified user does not have access to log into the
zone |
|||
| Description |
This packet is used to delete the specified zone, subordinates, and all related authorities. |
10.3.8 GNS_PURPOSE_SETZONEPROPERTY
| ID | 0008 | |||
| Name | Sets a zone-specific property | |||
| Task | GNS_TASK_ZONE | |||
| FQGN | The zone containing the property | |||
| Request Data |
|
|||
| Response Data | <A response is required, but there is no data> | |||
| Error Codes |
GNS_ERR_USER_DOES_NOT_EXIST - The client is not logged in. GNS_ERR_ACCESS_DENIED - The client is not logged in as a user who has access to perform this operation. GNS_ERR_INVALID_TOKEN - The token parameter was invalid. |
|||
| Description |
This packet is used to set generic property data for a specific zone. Here are some example uses for someone hosting a game at tedsgame.superfighter2004:
|
10.3.9 - GNS_PURPOSE_ZONETRANSFER
| ID | 0009 | |||||||||
| Name | Zone Information Transfer | |||||||||
| Task | GNS_TASK_ZONE | |||||||||
| FQGN | The wildcard filter of all the zones to acquire information for. This can also be the name of a single zone. | |||||||||
| Request Data |
|
|||||||||
| Response Data |
|
|||||||||
| Error Codes |
GNS_ERR_ACCESS_DENIED - The logged in user does not have read access to this zone GNS_ERR_INVALID_PARAMETER - The FQGN is of an invalid format GNS_ERR_EMPTY_PARAMETER - The FQGN is of an invalid format GNS_ERR_ZONE_DOES_NOT_EXIST - The FQGN does not exist |
|||||||||
| Description |
This packet is used to get authority information and/or generic data for a specific zone. This is the main mechanism for clients to get lists of active video games. For example, to get a list of active WidgetFighter games, you can send this packet with flags one and two set, and the FQGN of the packet would be *.WidgetFighter. The hierarchy is described by the Action field at the end of each zone's information. |
10.3.10 - GNS_PURPOSE_CHATLOGIN
| ID | 000A | ||
| Name | Chat Server Login | ||
| Task | GNS_TASK_CHAT | ||
| FQGN | The zone containing the chat server | ||
| Request Data |
|
||
| Response Data |
| ||
| Error Codes |
GNS_ERR_ACCESS_DENIED - The logged in user or chat nickname does not have read access to the chat server GNS_ERR_ALREADY_LOGGED_IN - There is already someone logged into the chat server with the desired nickname, and a new one could not be generated. |
||
| Description |
This packet is used in negotiating a chat server login between the GNS server and client. If a login is granted, the server responds to the client with their chat nickname. This may not be the same value as that requested because another client may be using it. If a chat nickname is permanently reserved on the chat server, the password must match that of the reserved chat user. Otherwise, the password is ignored. |
10.3.11 - GNS_PURPOSE_CHATLOGOUT
| ID | 000B |
| Name | Chat Server Logout |
| Task | GNS_TASK_CHAT |
| FQGN | The zone containing the chat server |
| Request Data | <A request is required, but there is no data> |
| Response Data |
<A response is required, but there is no data> |
| Error Codes | GNS_ERR_OPERATION_NOT_IN_PROGRESS - The client is not logged into the chat server. |
| Description |
This packet is sent to log a user out of a chat server |
10.3.12 - GNS_PURPOSE_JOINCHATCHANNEL
| ID | 000C | ||
| Name | Chat Server Channel Join | ||
| Task | GNS_TASK_CHAT | ||
| FQGN | The zone containing the chat server | ||
| Request Data |
|
||
| Response Data |
Chat User ID (32-bits) - The
unique ID of the chat user
Nickname (n bits of
zero-terminated Unicode string) |
||
| Error Codes |
GNS_ERR_OPERATION_IN_PROGRESS - The client is already logged into the chat channel GNS_ERR_USER_DOES_NOT_EXIST - The client is not logged into the chat server |
||
| Description |
This packet is sent to log a user on a chat server into a chat channel. If the login is successful, everybody in the channel must be notified of the user's presence with a response. |
10.3.13 - GNS_PURPOSE_LEAVECHATCHANNEL
| ID | 000D | ||
| Name | Chat Server Channel Leave | ||
| Task | GNS_TASK_CHAT | ||
| FQGN | The zone containing the chat server | ||
| Request Data |
|
||
| Response Data |
|
||
| Error Codes |
GNS_ERR_OPERATION_NOT_IN_PROGRESS - The client is not logged into the chat channel GNS_ERR_USER_DOES_NOT_EXIST - The client is not logged into the chat server |
||
| Description |
This packet is sent to log a user out of a chat channel. If the logout is successful, everyone in the channel must be notified with a response. |
10.3.14 GNS_PURPOSE_SETCHATUSERPROPERTY
| ID | 000E | ||
| Name | Set chat user-defined property | ||
| Task | GNS_TASK_CHAT | ||
| FQGN | The zone containing the chat server | ||
| Request Data |
|
||
| Response Data | <A response is required, but there is no data> | ||
| Error Codes | GNS_ERR_USER_DOES_NOT_EXIST - The client is not logged into the chat server | ||
| Description |
This packet is used to set generic property data for a specific chat user. Some examples include:
It is up to the implementation of the server to decide whether to keep the information permanently or not. |
10.3.15 - GNS_PURPOSE_CHANNELXFER
| ID | 000F | |
| Name | Chat Server Channel List Transfer | |
| Task | GNS_TASK_CHAT | |
| FQGN | The zone containing the chat server | |
| Request Data |
Flags
(32 bits) - The flags
of the operation: 1=Get channel list. Other values are reserved for the future.
|
|
| Response Data |
Based on which flags are set, the following
content will be given: |
|
| Error Codes |
GNS_ERR_INVALID_PARAMETER - The flags parameter is not supported GNS_ERR_ZONE_DOES_NOT_EXIST - The FQGN does not exist or has no chat room authority |
|
| Description |
This packet is sent to get a list of all chat channel names. |
10.3.16 - GNS_PURPOSE_CHANNELDATAXFER
| ID | 0010 | ||
| Name | Chat Channel Data Transfer | ||
| Task | GNS_TASK_CHAT | ||
| FQGN | The zone containing the chat server | ||
| Request Data |
|
||
| Response Data |
Based on which flags are set, the following
content will be given in the form of an array of values: |
||
| Error Codes |
GNS_ERR_INVALID_PARAMETER - The flags parameter is not supported GNS_ERR_ZONE_DOES_NOT_EXIST - The FQGN does not exist or has no chat server authority |
||
| Description |
This packet is sent to get a list of users in a chat channel, as well as user-specific data, such as chat avatar or other profile information. |
10.3.17 - GNS_PURPOSE_CHATMSG
| ID | 0011 | ||
| Name | Chat Message | ||
| Task | GNS_TASK_CHAT | ||
| FQGN | The zone containing the chat server | ||
| Request Data |
|
||
| Response Data |
<A response is required, but there is no data> Everyone else:
|
||
| Error Codes | GNS_ERR_USER_DOES_NOT_EXIST - The client is not logged into the chat room | ||
| Description |
This packet is used to send a chat message to a specific channel. |
10.3.18 - GNS_PURPOSE_PRIVCHATMSG
| ID | 0012 | ||
| Name | Private Chat Message | ||
| Task | GNS_TASK_CHAT | ||
| FQGN | The zone containing the chat server | ||
| Request Data |
|
||
| Response Data | <A response is required, but there is no data> | ||
| Error Codes | GNS_ERR_USER_DOES_NOT_EXIST - The client is not logged into the chat room, or the user nickname does not exist. | ||
| Description |
This packet is used to send a chat message to a specific user. |
10.3.19 - GNS_PURPOSE_DOWNLOADCONTENT
| ID | 0013 | ||||
| Name | Content Download | ||||
| Task | GNS_TASK_CONTENT | ||||
| FQGN | The zone containing the content | ||||
| Request Data |
|
||||
| Response Data |
|
||||
| Error Codes |
GNS_ERR_INVALID_PARAMETER - The size was too large for the server to support, the start was after the end, or the file media type was not supported. GNS_ERR_OPERATION_IN_PROGRESS - A content transfer is already in progress. GNS_ERR_ACCESS_DENIED - The client does not have permission to access the specified file GNS_ERR_FILE_ACCESS_DENIED - The server does not have permission to access the specified file, or the file does not exist. |
||||
| Description |
This packet is used to negotiate the download of content from a GNS server. Content exists per-zone. The server is responsible for validating the parameters of the request packet. If the content file does not exist, an error packet must be returned. Otherwise, the server responds with the intended file transfer parameters. The filename field must have a prefix describing the media type. The only standard type currently supported is "file:\\", which means the media is an actual file. Following this is the path of the file relative to the server's working directory, or, an absolute file path. Here are some valid examples: file:\\c:\gns\content\addon.dat |
10.3.20 - GNS_PURPOSE_UPLOADCONTENT
| ID | 0014 | |||
| Name | Content Upload | |||
| Task | GNS_TASK_CONTENT | |||
| FQGN | The zone containing the content | |||
| Request Data |
|
|||
| Response Data |
|
|||
| Error Codes |
GNS_ERR_INVALID_PARAMETER - The size was too large for the server to support, or the start was after the end. GNS_ERR_OPERATION_IN_PROGRESS - A content transfer is already in progress. GNS_ERR_ACCESS_DENIED - The client does not have permission to access the specified file GNS_ERR_FILE_ACCESS_DENIED - The server does not have permission to access the specified file, or the file does not exist. |
|||
| Description |
This packet is used to negotiate the upload of content from a GNS server. Content exists per-zone. The server is responsible for validating the parameters of the request packet, and should throw an error if they are invalid. |
10.3.21 - GNS_PURPOSE_CONTENTFRAME
| ID | 0015 | |||
| Name | Content Frame | |||
| Task | GNS_TASK_CONTENT | |||
| FQGN | The zone containing the content | |||
| Request Data |
|
|||
| Response Data |
Based on which flags are set, the following
content will be given: |
|||
| Error Codes |
GNS_ERR_OPERATION_NOT_IN_PROGRESS - There is not a file transfer in progress GNS_ERR_FILE_ACCESS_DENIED - A read or write operation failed. |
|||
| Description |
Content frame request and response are exchanged back and forth between a client and a server until the content transfer is complete. |
10.3.22 - GNS_PURPOSE_CANCELXFER
| ID | 0016 |
| Name | Cancel Content Transfer |
| Task | GNS_TASK_CONTENT |
| FQGN | The zone containing the content |
| Request Data |
<A request is required,
but there is no data>
|
| Response Data |
<A response is required, but there is no data> |
| Error Codes | GNS_ERR_OPERATION_NOT_IN_PROGRESS - There is not a file transfer in progress |
| Description |
This packet is sent by either a client or a server to signal the cancelling of a transfer. Transfers should also be cancelled if any error packets are sent from either side. |
10.3.23 - GNS_PURPOSE_XFERCOMPLETE
| ID | 0017 |
| Name | Content Transfer Complete |
| Task | GNS_TASK_CONTENT |
| FQGN | The zone containing the content |
| Request Data |
<A request is required,
but there is no data>
|
| Response Data |
<A response is required, but there is no data> |
| Error Codes | <none> |
| Description |
This packet is sent by either a client or a server to signal the completion of a transfer. |
10.3.24 - GNS_PURPOSE_PING
| ID | 0018 |
| Name | Content Transfer Complete |
| Task | GNS_TASK_PING |
| FQGN | Must be an empty zero-terminated unicode string |
| Request Data |
<User-defined payload>
|
| Response Data |
<The User-defined payload sent in the request> |
| Error Codes | <none> |
| Description |
This packet is sent by a client to ping the GNS server. |
10.3.25 - GNS_PURPOSE_CONSOLE_LOGIN
| ID | 0019 |
| Name | Console Login |
| Task | GNS_TASK_CONSOLE |
| FQGN | Must be an empty zero-terminated unicode string |
| Request Data |
None
|
| Response Data |
Console ID (32-bits) - The unique ID of your new console |
| Error Codes |
GNS_ERR_ZONE_DOES_NOT_EXIST - The requested zone does not exist GNS_ERR_AUTHORITY_DOES_NOT_EXIST - The requested zone does not have a console authority GNS_ERR_ACCESS_DENIED - You do not have access to open a console GNS_ERR_TOO_MANY_CONSOLES - You have too many consoles open |
| Description |
This packet is sent by a client to request a text-based console interface to the GNS server. |
10.3.26 Console Logout
| ID | 001A |
| Name | Console Logout |
| Task | GNS_TASK_CONSOLE |
| FQGN | Must be an empty zero-terminated unicode string |
| Request Data |
Console ID (32-bits) - The unique ID of the console |
| Response Data |
<A response is required, but there is no data> |
| Error Codes |
GNS_ERR_ZONE_DOES_NOT_EXIST - The requested zone does not exist GNS_ERR_AUTHORITY_DOES_NOT_EXIST - The requested zone does not have a console authority GNS_ERR_ACCESS_DENIED - You do not have access to close a console GNS_ERR_CONSOLE_DOES_NOT_EXIST - The console does not exist |
| Description |
This packet is sent by a client to request a console interface to the GNS server. |
10.3.27 - Console Execute
| ID | 001B | ||
| Name | Console Command Execution | ||
| Task | GNS_TASK_CONSOLE | ||
| FQGN | Must be an empty zero-terminated unicode string | ||
| Request Data |
|
||
| Response Data |
Console ID (32-bits)
- The unique ID of the console |
||
| Error Codes |
GNS_ERR_ZONE_DOES_NOT_EXIST - The requested zone does not exist GNS_ERR_AUTHORITY_DOES_NOT_EXIST - The requested zone does not have a console authority GNS_ERR_ACCESS_DENIED - You do not have access to write to a console GNS_ERR_CONSOLE_DOES_NOT_EXIST - The console does not exist |
||
| Description |
This packet is sent by a client to send a command to a console. The return value is a variant which contains the console response. |
10.3.28 - Bug Report
| ID | 001C |
| Name | Bug Report |
| Task | GNS_TASK_ERRREPORT |
| FQGN | Must be an empty zero-terminated unicode string |
| Request Data |
Report (n bits) - The proprietary error report |
| Response Data |
<A response is required, but there is no data> |
| Error Codes |
GNS_ERR_ZONE_DOES_NOT_EXIST - The requested zone does not exist GNS_ERR_AUTHORITY_DOES_NOT_EXIST - The requested zone does not have a bug report authority GNS_ERR_ACCESS_DENIED - You do not have access to submit a bug report
|
| Description |
This packet is sent by a client when a client-side application has unexpectedly terminated. |
10.3.29 - Content Catalog
| ID | 001D |
| Name | Content Directory Catalog |
| Task | GNS_TASK_CONTENT |
| FQGN | Must be an empty zero-terminated unicode string |
| Request Data |
<A request is required, but there is no data> |
| Response Data |
Catalog (n bits of 16-bit Unicode zero-terminated characters) - The comma-delimited catalog string that describes the file structure of the home content directory of the zone. |
| Error Codes |
GNS_ERR_ZONE_DOES_NOT_EXIST - The requested zone does not exist GNS_ERR_AUTHORITY_DOES_NOT_EXIST - The requested zone does not have a content authority GNS_ERR_ACCESS_DENIED - You do not have access to get a catalog
|
| Description |
This packet is sent by a client when requesting a list of all files in the content directory of the zone. This is typically used for product updates or just getting a directory listing. |
10.4 VARIANTS
A variant is a union of a set of possible data types located in the same area of memory. This protocol treats as variant as a block of data with a defined structure. Variants in the context of GNS have three components:
| Type (8 bits) |
0: Empty |
| Size (32 bits) | If the variant is type 6 (raw data), this is the size, in bytes, of the data. |
| Data (n bytes) | Variant data (This is endian-sensitive for all types besides raw data and unicode string) |
That is the format in which variants must be sent in packets.
10.5 STANDARD PORTS
The standard port for all Internet-based GNS operations is TCP port 20345. UDP port 20345 is the standard for GNS-level pings.
10. ERROR CODES
When a client sends a packet to a server, and the server is unable to process the packet in a manner that the client expects, the server must respond by sending a packet with an error code. Here is a list of error codes and their names copied from the official implementation written in C++:
GNS_ERR_SUCCESS 0x00000000
GNS_ERR_ACCESS_DENIED 0x00000001
GNS_ERR_EMPTY_PARAMETER 0x00000002
GNS_ERR_INVALID_PARAMETER 0x00000003
GNS_ERR_OUT_OF_MEMORY 0x00000004
GNS_ERR_ZONE_DOES_NOT_EXIST 0x00000005
GNS_ERR_AUTHORITY_DOES_NOT_EXIST 0x00000006
GNS_ERR_SOCKET_CREATION_FAILED 0x0000000
GNS_ERR_FAILED_TO_CONNECT 0x00000008
GNS_ERR_XMIT_FAILED 0x00000009
GNS_ERR_PKT_INVALID_SIZE 0x0000000A
GNS_ERR_INVALID_TOKEN 0x0000000B
GNS_ERR_NO_DATA_AVAILABLE 0x0000000C
GNS_ERR_USER_ALREADY_EXISTS 0x0000000D
GNS_ERR_USER_DOES_NOT_EXIST 0x0000000E
GNS_ERR_GROUP_DOES_NOT_EXIST 0x0000000F
GNS_ERR_GROUP_ALREADY_EXISTS 0x00000010
GNS_ERR_ALREADY_LOGGED_IN 0x00000011
GNS_ERR_TOO_MANY_USERS 0x00000012
GNS_ERR_CHAT_CHANNEL_DOES_NOT_EXIST 0x00000013
GNS_ERR_TOO_MANY_CHAT_CHANNELS 0x00000014
GNS_ERR_FILE_ACCESS_DENIED 0x00000015
GNS_ERR_OPERATION_IN_PROGRESS 0x00000016
GNS_ERR_BUSY 0x00000017
GNS_ERR_OPERATION_NOT_IN_PROGRESS 0x00000018
GNS_ERR_NO_AUTHORITY 0x00000019
GNS_ERR_TASK_DOES_NOT_EXIST 0x0000001A
GNS_ERR_OVERFLOW 0x0000001B
GNS_ERR_TOO_MANY_CONSOLES 0x0000001C
GNS_ERR_CONSOLE_DOES_NOT_EXIST 0x0000001D
GNS_ERR_PLUGIN_DOES_NOT_EXIST0x0000001E
GNS_ERR_PLUGIN_CONNECTION_FAILED 0x0000001F