Codecore Logo
Quick Search
»
Advanced Search »

Remote Touch Screen Protocol

RSS

Overview

This thin client touch screen protocol is designed to ease the development and maintenance of touch screen viewer client applications on 3rd party systems such as mobile devices or linux, etc.

Client applications do not need to know how user interface controls are drawn or behave (such as a button control or slider control). The client simply needs to send user interaction commands such as when the screen is touched, and know a few drawing commands.

There are two rendering modes available:

  • Snapshot - The Touch Service (server) sends screen snapshot images to the client to be drawn directly to the screen whenever an area of the screen changes. This is the simplest mode as only a small subset of the commands are used, however it comes at the cost of more network traffic to send the image data.

  • Granular Drawing Commands - The Touch Service (server) sends specific drawing commands such as DrawText, DrawBorder, or DrawNamedImage. This is the most optimized mode but since some client platforms may not fully support all the drawing concepts (such as specific font names or alpha blending) the resulting touch screen display may not look exactly as intended.

Client Application Components

The client application is usually segmented into the following components (depending on the rendering mode):

Snapshot Mode:

  • A user interface which the drawing buffer is drawn to and user actions such as screen touches are detected.
  • A thread which reads the incoming data.

Granular Drawing Commands Mode:

  • A user interface which the drawing buffer is drawn to and user actions such as screen touches are detected.
  • An in-memory drawing buffer for double buffering to prevent screen flickering.
  • A clipping area stack which prevents drawing in unwanted areas.
  • A thread which reads the incoming data.
  • A queue which drawing commands are added to, processed, and removed.
  • An image cache which persists named images received from the server.

User Interface

The user interface should have a minimum of the following:

  • A settings interface to edit the following:
    • The Touch Service hostname.
    • Username and Password.
    • (Optional) The rendering mode.
  • An area or window which displays the rendered touch screen interface.
  • Detect when the user interacts with the touch screen interface (touch/mouse click/etc).

In-Memory Drawing Buffer

When using the Granular Drawing Commands rendering mode, double buffering should be used to minimize screen flickering caused by drawing. Each drawing command sequence will begin with a StartDrawing command and end with an EndDrawing command. Drawing should be done to an in-memory drawing buffer/bitmap, then when the EndDrawing command is processed the buffer should be copied to the appropriate location on the screen.

Clipping Area Stack

When using the Granular Drawing Commands rendering mode, the server will send clipping area information to the client in the form of Push commands and Pop commands for use with a stack data structure.

The clipping area stack should be cleared when the EndDrawing command is received.

For more information see the PushClippingArea and PopClippingArea commands.

Incoming Data Reader Thread

The incoming and outgoing data flow will contain a stream of message headers and payloads. The message header indicates the length of the following payload. In the case when the payload length is zero, no payload will be sent and therefore the next 11 bytes will be the next header.

Example stream:

Header (11 bytes) (suppose it indicates a 20 byte payload length)
Payload (20 bytes)
Header (11 bytes) (suppose it indicates a 5 byte payload length)
Payload (5 bytes)
Header (11 bytes) (suppose it indicates a 0 byte payload length)
Header (11 bytes) (suppose it indicates an 8 byte payload length)
Payload (8 bytes)
...

Detecting Data Loss

TCP connections guarantee data will be received in order with no errors, however the header packet still contains several ways to detect the header packet as well as detecting a corrupt header or payload which the server may have inadvertently sent. Although the Touch Service should not send any corrupt packets the client application should employ at least one of the following tests to ensure the received data is as expected.

  1. The 1st byte of the header is always 0x00 and the last byte of the header is always 0x0D. The reader should ensure that the incoming message matches this.
  2. The header contains a checksum of the 1st 9 bytes of the header. The reader can verify the checksum to ensure the header is valid.
  3. Each header has an incremented 16bit identifier. If a header is received that has an ID that is not 1 more than the previous, the reader can assume it missed a header.
  4. The payload length and checksum are included in the header. The reader can calculate the payload checksum to ensure it is valid.

Drawing Command Queue

When using the Granular Drawing Commands rendering mode, the client application will need a queue dedicated for incoming drawing commands. The draw commands should be rendered in the order received, however when a DrawNamedImage command is received the client must have a copy of the named image before it can render it. If the client does not have a copy of the named image it must stop processing commands in the queue and send the RequestNamedImage command to the server which will eventually result in the server sending the image within the NamedImage message payload. While the client is waiting for the named image to arrive the server will continue to send draw commands which the client must append to the drawing queue. Once the NamedImage payload is received for the pending request the client can continue processing the queue. A set of named images should be cached locally on the client device to improve performance. The developer will need to make an educated decision on balancing the number of cached image with storage limitations of the client device. If a requested named image is not received within 30 seconds it should drop the connection and reconnect.

Image Cache

When using the Granular Drawing Commands rendering mode, to provide optimal performance the client application should implement a local image cache to store received named images. In cases where client device storage or memory is limited the client application should only cache the most recently used or perhaps most often used images.

When a DrawNamedImage command is received the client application should do the following:

  • Check if the named image is in the local image cache.
  • If it is in the cache then:
    • The image hashes should be compared to determine if the image is different on the server.
      • If the image is up to date then it should be drawn.
  • If the image is not in the cache or it is not up to date then the client application should:
    • Stop processing drawing commands from the drawing command queue.
    • Send a RequestNamedImage command with the image path.
    • When the NamedImage message is received:
      • The image should be stored in the local cache.
      • Determine if the command queue can be processed (ie, did we receive the requested named image).

Protocol Basics

Connection

Transport: TCP
Port: 33907

The protocol uses a binary message structure, including a message header and a payload which follows it. Some simple messages do not have a payload.

Message Format

A message consists of an 11 byte fixed length header and a payload. The message header indicates the type of payload which follows and it's length.

Datatype definitions are discussed in the next section.

The header is a fixed length 11 bytes:


[0-0]   Byte   : Start of Header  : Always 0x00.
[1-2]   UInt16 : Message ID       : A rolling incremental 16bit integer sequence number. The 1st message has an ID of 0.
[3-3]   Byte   : Payload Type     : Identifies the format and content of the payload following the header.
[4-7]   UInt32 : Payload Length   : The number of bytes in the payload.
[8-8]   Byte   : Payload Checksum : The checksum of only the payload bytes.
[9-9]   Byte   : Header Checksum  : The checksum of the header except this checksum byte and the following byte.
[10-10] Byte   : End of Header    : Always 0x0D.

Data Types

The following datatypes are used in this document.

All numeric multibyte values are transmitted using little endian.

Simple Types:

Byte      : 8  bit (1 byte)
Int16     : 16 bit (2 bytes) signed integer
Int32     : 32 bit (4 bytes) signed integer
UInt16    : 16 bit (2 bytes) unsigned integer
UInt32    : 32 bit (4 bytes) unsigned integer
Single    : 32 bit (4 bytes) single precision IEEE-754 floating point number
Double    : 64 bit (8 bytes) double precision IEEE-754 floating point number
Boolean   : 8  bit (1 byte)  0=false, 1=true.
DateTime  : 64 bit (8 bytes). The number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001.

Composite Types:

String
  Length : Int32
  Bytes  : The UTF8 encoded string.

Rectangle
  X      : Int16
  Y      : Int16
  Width  : Int16
  Height : Int16

Point
  X      : Int16
  Y      : Int16

Size
  Width  : Int16
  Height : Int16

Color
  A      : Byte    : The Alpha (transparency) component of the color.
  R      : Byte    : The Red component of the color.
  G      : Byte    : The Green component of the color.
  B      : Byte    : The Blue component of the color.

Font
  Name   : String  : The name of the font.
  Size   : Single  : The em size of the font.
  Byte   : Style   : 0=Regular, 1=Bold, 2=Italic, 4=Underline, 8=Strikeout. These can be OR'd.

ByteArray
  Length : Int32
  Bytes  : The byte array bytes.

Checksum Calculation

The header contains two checksums, one for the payload and one for the first 9 bytes of the header.

If there is no payload the payload checksum byte should be zero.

The following is a sample function (written in C#) to calculate the checksum of a byte array.


byte CalculateByteChecksum(byte[] b, int startIndex, int length)
{
    // Returns the two's complement of the 8 bit sum of the byte array.

    long sum = 0;
    for (int i = startIndex; i < startIndex + length; i++)
        sum += (long)b[i];

    sum = -(sum % (0xFF + 1));

    return (byte)sum;
}

Typical Sessions

A session always begins with the client sending the Hello command which specifies the rendering mode as well as other details about the client. This also begins the challenge-response authentication handshake sequence. Once authenticated the server will begin sending drawing commands to the client. Depending on which rendering mode was specifed in the Hello command, the server will either send messages indicating which parts of the screen have changed, or it will send granular drawing commands for the client to draw the changes.

Rendering Modes

The protocol offers two rendering modes which affect the types of commands sent from the server and how the client application is to draw the touch screen.

Implementing a client to receive snapshots only is a quick way to get up and running however the overhead of the image data being sent can be slow for distant network connections. For optimal performance it may be worthwhile to take the extra effort and implement granular draw command support. However since some client platforms may not fully support the drawing commands, the snapshot mode may be the best option for the client.

Snapshot Support Only

Snapshot mode is the simplest rendering mode. The server notifies the user whenever an area of the screen changes and the client application subsequently requests the changed image area from the server.

This mode is not as efficient as the Granular Draw Commands mode since the overhead of sending the images can be very high.

After authentication the communication process is asynchronous. Any number of commands can be received from the server at any time. When using the snapshot rendering mode the client must determine how often it wishes to request screen image areas and which sections of the screen to request based on the incoming ScreenChange messages and the changed screen bounds specified in it's payload. The client should not send a request for every received ScreenChange message since many messages may be received in a fraction of a second. It is more efficient for the client application to optimize it's screen snapshot requests.

The following commands are required to be supported by the client to use snapshot mode:

  • Ping
  • Pong
  • Disconnect
  • ContinueSession
  • ContinueSessionResult
  • Hello
  • AuthenticateChallenge
  • Authenticate
  • AuthenticationResult
  • TouchEvent
  • ShowMessage
  • ChangeScreenMode
  • ScreenChange
  • RequestSnapshot
  • DrawImage
  • Exit

The following is an example snapshot rendering mode session:

Authentication:
  • Client Sends: Hello
  • Client Receives: AuthenticateChallenge
  • Client Sends: Authenticate
  • Client Receives: AuthenticationResult

Retrieve the entire touch screen image:
  • Client Receives: ScreenChange. The entire touch screen image is ready.
  • Client Sends: RequestSnapshot. The client needs the entire touch screen image.
  • Client Receives: DrawImage. The entire touch screen image is received.

Nothing happens for a while, so keep the connection open:
  • Client Receives: Ping
  • Client Sends: Pong
  • ...
  • Client Receives: Ping
  • Client Sends: Pong

A small part of the touch screen changed:
  • Client Receives: ScreenChange. Something on the touch screen changed.
  • Client Sends: RequestSnapshot. The client requests just the changed area.
  • Client Receives: DrawImage. The partial touch screen image is received.

Many parts of the touch screen changed:
  • Client Receives: ScreenChange
  • Client Receives: ScreenChange
  • Client Receives: ScreenChange
  • Client Receives: ScreenChange
  • Client Sends: RequestSnapshot
  • Client Receives: ScreenChange
  • Client Receives: ScreenChange
  • Client Receives: DrawImage
  • Client Receives: ScreenChange

The client application is going to exit:
  • Client Sends: Disconnect

Granular Draw Command Support

Granular draw command support sends more granular draw commands for the client to render such as drawing text, drawing a border, or an image, etc.

An example session:

Authentication:
  • Client Sends: Hello
  • Client Receives: AuthenticateChallenge
  • Client Sends: Authenticate
  • Client Receives: AuthenticationResult

The entire touch screen begins rendering:
  • Client Receives: StartDrawing. The client adds the clipping area to the clipping stack and sets the clipping area.
  • Client Receives: FillRectangle. The client fills a rectangle in the buffer.
  • Client Receives: FillRectangle. The client fills a rectangle in the buffer.
  • Client Receives: DrawText. The client draws the text in the buffer.
  • Client Receives: DrawBorder. The client draws the border in the buffer.
  • Client Receives: EndDrawing. The client draws the buffer to the screen and clears the clipping stack.

A more complicated session snippet:

The entire touch screen begins rendering:
  • Client Receives: StartDrawing. The client adds the clipping area to the stack and sets the clipping area.
  • Client Receives: FillRectangle. The client fills a rectangle in the buffer.
  • Client Receives: FillRectangle. The client fills a rectangle in the buffer.
  • Client Receives: DrawNamedImage. The client doesn't yet have the named image...
  • Client Sends: DrawNamedImage. ...so it requests the named image
  • Client Receives: DrawText. Meanwhile the server keeps sending draw commands,
  • Client Receives: DrawBorder. so the client must let these these commands queue up until the named image is received.
  • Client Receives: NamedImage. The client received the requested named image and caches it and resumes processing the queued commands.
  • Client Receives: EndDrawing. The client draws the buffer to the screen and clears the clipping stack.

Commands

General

Ping

Use to test the network connection. A Pong response should be received. If the server has not received any data in 30 seconds the server will drop the client connection.

Payload Type ID: 0
Direction: Bi-directional
Payload: This command has no payload.

Pong

Send this when a Ping command is received to ensure the connection has not dropped. See the Ping command.

Payload Type ID: 1
Direction: Bi-directional
Payload: This command has no payload.

Error

When the Error payload is received, the server will forcibly disconnect and the client application should display the message and attempt to reconnect.

Payload Type ID: 2
Direction: Server -> Client
Payload:

String : Title Text
String : Message
String : Exception type name
String : Source

Disconnect

Tells the client or server to close the connection. Send them command before closing the connection.

Payload Type ID: 3
Direction: Bi-directional
Payload: This command has no payload.

User Authentication

The first communication after connections must be the Hello command from the client to the server. The Hello command introduces the client to the server with session configuration information and initiates the authentication handshaking sequence.

The authentication handshaking sequence uses the well known challenge response paradigm. This four step process allows the user to be authenticated without needing the user's password to be transferred over the network, therefore preventing any ease-droppers from obtaining the password.

The authentication handshaking process must follow the following sequence:

  1. Client Sends: Hello
  2. Client Receives: AuthenticateChallenge
  3. Client Sends: Authenticate
  4. Client Receives: AuthenticationResult

If the authentication fails:

The connection will be dropped after the server sends the AuthenticationResult response.

If the authentication is successful:

The client will begin receiving drawing commands based on the rendering mode specified in the Hello command.

Hello

This command should be sent from the client as soon as a connection is established to send details about the client and to initiates authentication handshaking. If the server does not receive this command within 30 seconds after a connected in established the connection will drop.

The server will respond with an AuthenticateChallenge payload which contains a randomly generated list of bytes. These bytes will be used in a hashing algorithm to send back a response to the server without sending the user's password or password hash.

Payload Type ID: 4
Direction: Client -> Server
Payload:

Byte : Protocol Version. This should be set to 1.
Byte : Client Application ID. Set this to 0 if you do not have an ID. Please request an ID from us.
Byte : Rendering Mode. 0=Snapshot Support Only, 1=Granular Draw Command Support
Size : Screen Size. This is the native size of the client device's screen.
Byte : Pixel Depth Bit Count. This is usually 24 or 32.
Boolean : Supports Alpha Channel.
String : Unique Client ID. An ID that uniquely identifies the individual client device.
Byte : Snapshot rendering mode image format. 0=png, 1= jpeg.
Byte : Snapshot rendering mode jpeg quality. 0(lowest) to 100(highest).

Rendering Mode Overview:

The rendering mode is discussed in more detail elsewhere in this document.

Snapshot mode simply sends screen snapshot images of the areas of the screen that have changed to the client.
Granular draw command support sends more granular draw commands for the client to render such as drawing text, drawing a border, or an image, etc.

Implementing a client to received snapshots only is a quick way to get up and running however the overhead of the image data being sent can be very slow for slow network connections. For optimal performance it is worthwhile to take the extra effort and implement granular draw command support.

AuthenticateChallenge

This is the response to the Hello command.

Payload Type ID: 5
Direction: Server -> Client
Payload:

ByteArray: A random authentication list of bytes from the server formatted in as a hexadecimal string.

The client should take the following steps:

  1. Assign the received byte array to a variable named t1.
  2. Calculate the MD5 hash of the user entered password.
  3. Create another random list of bytes named t2. The recommended length is between 20 and 40 bytes long. Any length will work, however longer lengths are more secure.
  4. Calculate the MD5 hash of the following contiguous bytes: t2 + password hash + t1
  5. Send the Authenticate command to the server and include t2 and the user name.

The server will then compute the same hash to determine if they match. If they do match then the user entered password is known to be correct.

Authenticate

Requests that the server authenticate a user. This command should be sent after the AuthenticateChallenge command is received by the client. By using this approach we can eliminate the need to transmit the password or the password's hash. The server will respond with the AuthenticationResult command.

Payload Type ID: 6
Direction: Client -> Server
Payload:

String: User name
ByteArray: A random authentication token from the client in hex. The recommended length is between 20 and 40 bytes long. Any length will work, however longer lengths are more secure. Overly long values will slow down network performance.
ByteArray: The resulting MD5 hash in hex of: t2 + password + t1

AuthenticationResult

This command is sent in response to the Authenticate command and indicates if the user authentication was successful.

Payload Type ID: 7
Direction: Server -> Client
Payload:

Byte : Authentication Result. 0=Success, 1=Invalid username/password, 2=Account is disabled, 3=User is blocked by time restrictions.
Size : The size of the touchscreen that will be rendered.
Color : The touch screen's background color. This is useful when areas of the screen need to be painted which are not apart of the touch screen interface, such as when there is a difference between the touch screen and display's aspect ratio.
ByteArray : A 16 byte session identifier which can be used when reconnecting after a disconnection to continue the session. This will not exist in version 1.5 and earlier so check the payload size before reading.

Session Continuation

ContinueSession

Requests the continuation of a previously disconnected session. The session may have already expired.

Payload Type ID: 29
Direction: Client->Server
Payload:

ByteArray : Session ID (technically is a Windows GUID as 16 bytes)

ContinueSessionResult

Indicates if the session could be continued.

If the session is invalid the client should respond with a Hello message and re-authenticate.

Payload Type ID: 30
Direction: Server->Client
Payload:

Byte : Result. 0=Success, 1=Invalid or expired session id
Size : The size of the touchscreen that will be rendered.
Color : The touch screen's background color. This is useful when areas of the screen need to be painted which are not apart of the touch screen interface, such as when there is a difference between the touch screen and display's aspect ratio.

User Interface

ShowMessage

Includes a message that should be shown in the client application.

Payload Type ID: 8
Direction: Server -> Client
Payload:

Byte : Display Mode. 0=Non-intrusive, 1=Requires Acknowledgment
String : The message text.
String : The message title. The title and importance will not exist in version 1.5 and earlier so check the payload size before reading.
Byte : Importance. 0=Normal, 1=Important. Important notifications are usually emphasized via a different icon and/or background.

ChangeScreenMode

Indicates that the client should change the screen mode. This is caused by a Screen Mode button being pressed in the touch screen interface.

Payload Type ID: 9
Direction: Server -> Client
Payload:

Byte : The screen mode to change to. 0=Full Screen, 1=Windowed, 2=Minimized, 3=Toggle between fullscreen and windowed.

Some client device platforms may not support all the screen modes, in which case the client should either ignore the command or take the appropriate action for the platform.

Exit

Tells the client to exit. This is caused by an 'Exit Button' in the touch screen interface being pressed.

Payload Type ID: 10
Direction: Server -> Client
Payload: This command has no payload.

User Interaction

TouchEvent

The user has interacted with the screen by touching it or removing the touch from the screen.

Payload Type ID: 11
Direction: Client -> Server
Payload:

Byte : The touch event type. 0=Touch Down, 1=Touched, 2=Touch Up, 3=Double Touch, 4=Touch Move
Point : The location on the screen of the touch event.

Touch Event Types:
Touch Down : Occurs immediately when the screen is touched.
Touched : Occurs when the screen is touched and held for a 1/4 second, or when it is released (whichever occurs first).
Touch Up : Occurs when the user released their touch from the screen.
Double Touch: Occurs when the control is pressed twice in a short period of time.
Touch Move: The user has moved their finger across the screen. To reduce network and rendering overhead be sure to send this command at timed intervals, such as only after 1/10 second.

Example event sequences:

Simple button press:
Touch Down
Touched
Touch Up

Double Touch:
Touch Down
Touched
Touch Up
Touch Down
Double Touch
Touch Up

Touch and move such as using a slider:
Touch Down
Touch Move
Touched
Touch Move
Touch Move
Touch Up

Client Requests

RequestRedraw

Requests that the server send all the granular drawing commands necessary to redraw the specified area of the screen.

Command Payload ID: 12
Direction: Client -> Server
Payload:

Rectangle : The bounds to be redrawn.

RequestScreenSnapshot

Requests that the server send the current snapshot image of the specified area of the screen. The server responds with a DrawImage command.

Command Payload ID: 13
Direction: Client -> Server
Payload:

Rectangle : The bounds to be redrawn.

RequestNamedImage

Requests a named image from the server. The server responds with a NamedImage command. The RequestNamedImage command is usually sent after a DrawNamedImage command is received from the server but the client does not yet have an up to date locally cached copy of the named image.

Command Payload ID: 14
Direction: Client -> Server
Payload:

String : The image path.

Image paths are specified in the incoming DrawNamedImage message's payload and will look like:

IMAGE://MyImages/image.jpg
MEDIAIMAGE://musicmedialibrary/1382

The received image should be stored in a local image cache. See the Image Cache section for more details.

Download

NamedImage

This is the image data for a requested named image. This is usually a response to the RequestNamedImage command.

Command Payload ID: 15
Direction: Client -> Server
Payload:

String : Image Location (ie, image path)
Int32 : Image Hash. This is used to determine if the locally cached image is out of date and should be downloaded again.
Byte : Image Format. 0=Png, 1=Gif, 2=Jpeg, 3=Bmp
ByteArray : The image bytes.

Drawing

The following drawing commands should be added to the drawing command queue before processing. See the Drawing Command Queue section for more details.

StartDrawing

Indicates that a section of the screen is starting to be drawn. The client application should use double buffering to avoid flicker while drawing. The EndDrawing command will indicate when the area has completed drawing at which point the internal drawing buffer can be copied to the screen buffer (ie, double buffering).

Command Payload ID: 16
Direction: Client -> Server
Payload:

Rectangle : The initial clipping bounds.
UInt16 : X-Rounding on the clipping corners.
UInt16 : Y-Rounding on the clipping corners.

The clipping bounds should be pushed onto the client's clipping area stack. For more information on the needed clipping area stack see the PushClippingArea command.

EndDrawing

Indicates that a section of the screen has completed drawing. The clipping stack should be cleared and the final double buffered image should be painted on the client device's screen.

Command Payload ID: 17
Direction: Client -> Server
Payload: This command has no payload.

ScreenChange

When using the Snapshot Rendering Mode this command notifies the client application that the specified area of the screen has changed. The client should send the RequestSnapshot command to retrieve the changed area(s). Since multiple areas of the screen may change in a very short amount of time and some areas may even overlap it is recommended that the for network performance and efficiency the client application delay the snapshot request for a fraction of a second and then request the area(s) of the screen in a more optimized way.

Command Payload ID: 18
Direction: Client -> Server
Payload:

Rectangle : The screen bounds which changed.

PushClippingArea

In graphics rendering it is common to specify a clipping area which prevents drawing commands from rendering outside of the specified clipping area.

The client application should maintain a clipping area stack in which clipping areas are pushed onto the stack when the PushClippingArea command is received and then later popped from the stack when the PopClippingArea command is received. The payload specifies how this received clipping area should be treated. It can either be set as the new clipping area or it can intersect or exclude the current clipping area.

Command Payload ID: 19
Direction: Server -> Client
Payload:

Rectangle : The clipping bounds.
Byte : The mode. 0=Set, 1=Intersect, 2=Exclude
UInt16 : X-Rounding on the clipping corners.
UInt16 : Y-Rounding on the clipping corners.

Note: The clipping stack should always be cleared when the EndDrawing command is received.

PopClippingArea

The most recent clipping area should be popped off the stack.

Command Payload ID: 20
Direction: Server -> Client
Payload: This command has no payload.

FillRectangle

The client should draw a solid color filled rectangle.

Command Payload ID: 21
Direction: Server -> Client
Payload:

Rectangle : The rectangle coordinates to fill.
Color : The color to fill with.

FillLinearGradientRectangle

Fill a rectangle with a linear gradient.

Command Payload ID: 22
Direction: Server -> Client
Payload:

Rectangle : The rectangle coordinates to fill.
Color1 : The start color to fill with.
Color2 : The end color to fill with.
Single : The angle of the fill. Zero degrees is straight up.

DrawText

Draw the specified text string within the specified bounds.

Command Payload ID: 23
Direction: Server -> Client
Payload:

Rectangle : The bounds to draw the text within.
Color : The color of the text.
Font : The font to use.
Byte : Horizontal alignment. 0=Left, 1=Center, 2=Right.
Byte : Vertical alignment. 0=Top, 1=Center, 2=Bottom.
Byte : Trimming. 0=None, 1=Character, 2=Word, 3=Ellipsis Character, 4=Ellipsis Word, 5=Ellipsis Path
UInt16 : Format: 0=Wrap, 4096=No Wrap.
String : The text to draw.

If the specified font name is not installed on the client device which may be typical for non-Windows devices, the client should try to at least match the font family, otherwise it's up to the developer to choose the font substitute to draw.

DrawBorder

Draw a border.

Command Payload ID: 24
Direction: Server -> Client
Payload:

Rectangle : The rectangle coordinates for the border to be drawn an and/or inside of.
Color : The color of the border.
UInt16 : Border width in pixels.
Byte : Border Style. 0=None, 1=Dotted, 2=Dashed, 3=Solid, 4=Inset, 5=Outset.
UInt16 : The corner radius. 0=square.

DrawImage

Draw a PNG formatted image.

Command Payload ID: 25
Direction: Server -> Client
Payload:

Rectangle : The rectangle coordinates for the image.
Byte : The image opacity. 0=Transparent, 255=Fully Opaque.
Byte : Size Mode. 0=Normal, 1=Stretch To Fit, 2=Unused, 3=Center, 4=Proportional Stretch To Fit.
ByteArray : The PNG image data.

DrawNamedImage

Draw a named image.

IMPORTANT: If the named image is not in the local image cache or the local image is outdated (based on the image hash) then the client application will need to request the named image from the server with the RequestNamedImage Command. Since drawing commands MUST be executed in the order received the client application will need to stop processing incoming drawing commands until the named image is received. Because of this the client application will need to queue incoming drawing commands since the server will continue to send them while the client is waiting for the NamedImage response which includes the requested image. See the Drawing Command Queue section for more details on this.

Command Payload ID: 26
Direction: Server -> Client
Payload:

Rectangle : The rectangle bounds for the image.
Byte : The image opacity. 0=Transparent, 255=Fully Opaque.
Byte : Size Mode. 0=Normal, 1=Stretch To Fit, 2=Unused, 3=Center, 4=Proportional Stretch To Fit.
String : The image path.
Int32 : Image Hash. This is a numeric value which can be used to test if the locally cached image is up to date.

The image path will have one of the following prefixes:

IMAGE://
MEDIAIMAGE://
HTTP://

Examples:

IMAGE://MyImages/image.jpg
MEDIAIMAGE://musicmedialibrary/1382
HTTP://example.com/image.gif

IMAGE or MEDIAIMAGE paths should be requested from the server using the RequestNamedImage command. HTTP paths should be retrieved from the internet.

Named images should be cached on the client device for ideal performance. In cases where client device storage or memory is limited the client application should only cache the most recently used images. See the Image Cache section for more information.

DrawLine

Draw a line.

Command Payload ID: 27
Direction: Server -> Client
Payload:

Point1 : The first end point.
Point2 : The last end point.
Color : The color of the line.

StartApplication

Start an application on the client device.

Command Payload ID: 31
Direction: Server -> Client
Payload:

Int32: The type of application to start. 0=Default web browser.
String: The command line such as a complete url.

Connection Throttling

TODO: This section is incomplete.
Privacy Policy | Conditions Of Use

Copyright ©2014 Codecore Technologies, All rights reserved.