Create a Custom Client
Union Platform is designed to allow you, the developer, to create custom clients using any programming language that has TCP/IP socket or HTTP request capabilities, such as Java, Objective C, Python, C#, and C++.
To create a custom client application in the language of your choice, implement the Union client/server handshake, then communicate with the server using the set of commands defined by the UPC protocol (the XML-based message format used by Union clients to communicate with the Union server). The steps below describe process in detail.
If you make a custom client and would like to list it on unionplatform.com for others to use, please let us know!
Step 1. Connect to Union Server
Connect your client to Union Server using either a TCP/IP socket or HTTP.
TCP/IP Socket Connections
If you connect to Union Server with a socket, transmit your messages as UTF-8 encoded strings. Each transmission must contain one or more messages, and must be terminated by a null character (ASCII 0).
HTTP Connections
Union's HTTP implementation uses three HTTP request modes, as follows:
- Mode "d":
In mode "d", the HTTP request sends messages to the server, and also receives messages in the HTTP response. Mode "d" is used in one case only: to send the client's first message to the server, which is known as the "client hello" (u65 in UPC Protocol specification).
- Mode "s":
In mode "s", the HTTP request sends data to the server, and immediately receives an empty HTTP response. Mode "s" is used to send messages from the client to the server, such as a request to join a room.
- Mode "c":
In mode "c", the client opens an HTTP request, but sends no data to the server. Instead, the server holds the request open until it has messages to deliver to the client. In traditional terms, mode "c" is a "long poll". Mode "c" is used to send messages from the server to the client, such as the result of an attempt to join a room.
Client Hello
A custom client that communicates using HTTP must send an initial "client hello" (u65) using an HTTP POST with the following parameters:
- Name: mode
Value: d - Name: data
Value: A URI-encoded u65 message
The server's response (a u66 message) will contain a session id that must be included in all future requests.
Here is an example client hello HTTP Request:
POST / HTTP/1.1 Host: user1.net:10100 User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_8; en-us) AppleWebKit/530.19.2 (KHTML, like Gecko) Version/4.0.2 Safari/530.19 Content-Type: text/plain;charset=UTF-8 Referer: http://tryunion.com:80/orbiter Origin: http://tryunion.com:80 Accept: */* Accept-Language: en-us Accept-Encoding: gzip, deflate Content-Length: 327 Connection: keep-alive mode=d&data=%3CU%3E%3CM%3Eu65%3C%2FM%3E%3CL%3E%3CA%3EOrbiterMicro%3C%2FA%3E%3CA%3EMozilla%2F5.0%20(Macintosh%3B%20U%3B%20Intel%20Mac%20OS%20X%2010_5_8%3B%20en-us)%20AppleWebKit%2F530.19.2%20(KHTML%2C%20like%20Gecko)%20Version%2F4.0.2%20Safari%2F530.19%3B1.0.0%20(Build%20363)%3C%2FA%3E%3CA%3E1.9.1%3C%2FA%3E%3C%2FL%3E%3C%2FU%3E
Client-to-Server Messages
To send UPC messages to the server, the client must open an HTTP POST request with the following parameters.
- Name: mode
Value: s - Name: rid
Value: A sequential integer uniquely identifying the request among all mode "s" requests - Name: sid
Value: The session id delivered to the client in the server's hello (u66) message - Name: data
Value: One or more URI-encoded, UPC-formatted messages
A response with HTTP status 200 (OK) indicates that the server received the message.
Here is an example client-to-server HTTP Request:
POST / HTTP/1.1 Host: user1.net:10100 User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_8; en-us) AppleWebKit/530.19.2 (KHTML, like Gecko) Version/4.0.2 Safari/530.19 Content-Type: text/plain;charset=UTF-8 Referer: http://tryunion.com:80/orbiter Origin: http://tryunion.com:80 Accept: */* Accept-Language: en-us Accept-Encoding: gzip, deflate Content-Length: 148 Connection: keep-alive rid=1&sid=-14017638719a31704-b279-4bb9-81fa-db8fbb69ff75&mode=s&data=%3CU%3E%3CM%3Eu24%3C%2FM%3E%3CL%3E%3CA%3EchatRoom%3C%2FA%3E%3C%2FL%3E%3C%2FU%3E
Server-to-Client Messages
To receive UPC messages from the server, the client must open an HTTP POST request with the following parameters.
- Name: mode
Value: c - Name: rid
Value: A sequential integer uniquely identifying the request among all mode "c" requests - Name: sid
Value: The session id delivered to the client in the server's hello (u66) message
When the server has messages to deliver, it will send a response with HTTP status 200 (OK), and an HTTP body containing the messages, encoded as a UTF-8 string. Upon receiving the response, the client must open a new HTTP POST request with the preceding parameters. That is, the client must maintain an open mode "c" request at all times, otherwise the server will have no way to send messages to the client.
Here is an example server-to-client HTTP Request:
POST / HTTP/1.1 Host: user1.net:10100 User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_8; en-us) AppleWebKit/530.19.2 (KHTML, like Gecko) Version/4.0.2 Safari/530.19 Content-Type: text/plain;charset=UTF-8 Referer: http://tryunion.com:80/orbiter Origin: http://tryunion.com:80 Accept: */* Accept-Language: en-us Accept-Encoding: gzip, deflate Content-Length: 63 Connection: keep-alive rid=1&sid=-14017638719a31704-b279-4bb9-81fa-db8fbb69ff75&mode=c
Retry on HTTP Failure
If any HTTP request fails, it should be resent using the same request ID. The request ID is typically a simple incremented integer.
HTTP Heartbeat
In order to prevent the client's session from expiring, the client must send the server at least one message every client_timeout milliseconds, where client_timeout is the server's configurable session timeout, specified in Union Server's union.xml file.
Step 2. Implement the Union Handshake
When a Union client connects to Union server, it transmits and receives a standard set of UPC messages known as the Union handshake. The Union handshake sets up the client by assigning its initial attributes, client ID, and session ID. Your custom client must implement the Union Handshake according to the Union Handshake documentation.
Step 3. Send and Receive UPC Messages
Once your client has connected and completed the Union Handshake, it can communicate with the server using XML-based UPC messages. Each message has a message ID (specified in the tag
<U><M>u4</M><L><A>examples.chat</A><A></A></L></U>
For a complete list of available UPC messages consult the Union Protocol specification.
Happy multiuser coding!