Link Protocol for Client-Server Communication, v0.5

Basic Description

This document will describe the Link Protocol for Link client-server communication. Link client-server relationships involve the exchange and modification of geographic and graphic objects, called graphics, and information about those graphics.

The protocol is a set of requests and descriptions. A request or description makes up a section of the communication between a client and server. Each communication between the client and server can consist of any combination of these sections. Each section has a unique header, and one of two tail selections. The tail is important because it indicates whether another section follows the current one in the communication.

General Definitions

Versions

Number Notations and Definitions

Number Type

Definition

ASCII char

8 bit ASCII character

Unicode char

16 bit Unicode character.

int

32 bit signed.

float

32 bit signed. Follows the IEEE 754 standard for floating point numbers.

Definitions

These are the byte definitions for the objects being passed over the client-server connection.

Headers

Headers are important because they serve several important functions. They describe the section the precede, enabling the proper parsing to begin on the object. They also serve as reference markers on the communication socket in case the link communication loses synchronization. The < and > symbols combine to mark the location of a header. The client and server are expected to look for these markers byte-by-byte, identify the beginning of a section, and then parse the section accordingly.

Header Definitions

Query Sections

Header

Map Request

<MR>

Action Request

<AR>

GUI Request (Undefined)

<GUIR>

Description Sections

Header

Graphics Description

<G>

Gesture Description

<A>

GUI Description (Undefined)

<GUI>

No Action

<?>

Close Link

<C>

Graphic Objects

Header

Arc

<A>

Bitmap

<B>

Circle

<C>

Ellipse

<E>

Grid

<GD>

Line

<L>

Point

<PO>

Poly

<PY>

Raster

<RA>

Rectangle

<RE>

Text

<T>

Action Objects

Header

Update Graphics

<UG>

Update GUI (Undefined)

<UGUI>

Update Map (Server directed)

<UM>

Section Tail Definitions

Sections

Tail

End Section, more sections following.(END_SECTION)

Line Feed ASCII Character - '\n'

End Query/Description, nothing following.(END_TOTAL)

Carrige Return ASCII Character - '\r'


Query Definitions

Map Request

Graphics queries are used by the client to ask the server for graphics to draw on a map. The query provides several different parameters that let the server get an idea of what the bounds of the map are.

Map Request

# Bytes

Type

Description

4

byte

<MR>

4

float

Version number of the map request format.

4

float

The center latitude of the map, in decimal degrees.

4

float

The center longitude of the map, in decimal degrees.

4

float

The scale of the map, as in 1:<scale>.

4

int

The height of the map, in pixels.

4

int

The width of the map, in pixels.

4

int

The number of bounding polygons defining the areas of interest on the map.

Var

bounding polygon

Bounding Polygons. A series of bounding polygons.

4

int

The even number (N_FLTS) of 4 byte floats that follow in BoundsArray. The floats represent the coordinates of a bounding polygon, in pairs, each pair containing first a latitude and then a longitude. The coordinates of the polygon are defined to be listed in the clockwise direction.

4n

float

BoundsArray. A series of 4 byte floats, in pairs. Each pair represents a latitude and then a longitude in decimal degrees. There will be an even number greater than four of these floats sent, since they define a bounding polygon. If the number of points in the polygon is N_PTS, there will be 2*N_PTS = N_FLTS floats in BoundsArray.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

1

byte

Tail marker describing the end of this section, or the end of the entire communication (END_SECTION or END_TOTAL)

For the Map Request, the bounding polygon holds polygons defined by latitude and longitude values. These polygons are assumed to not cross over the dateline (+-180 degrees longitude), and do not contain the North or South pole. Areas that break these assumptions must be defined by multiple bounding polygons.

Bounding Polygon

# Bytes

Type

Description

4

int

The even number (N_FLTS) of 4 byte floats that follow in BoundsArray. The floats represent the coordinates of a bounding polygon, in pairs, each pair containing first a latitude and then a longitude. The coordinates of the polygon are defined to be listed in the clockwise direction.

4n

float

BoundsArray. A series of 4 byte floats, in pairs. Each pair represents a latitude and then a longitude in decimal degrees. There will be an even number greater than four of these floats sent, since they define a bounding polygon. If the number of points in the polygon is N_PTS, there will be 2*N_PTS = N_FLTS floats in BoundsArray.


Action Request

Gesture queries are used by the client to tell the server that a user event has happened, like a mouse movement or keyboard event. When used by the client, it is understood that the client will wait for some description from the server. The server can send a Gesture Query as well, but that would usually happen to tell the client what kind of events the server is interested in receiving.

Action Request for Mouse Events

# Bytes

Type

Description

4

ASCII char

<AR>

4

float

Version number of the action request format.

4

int

descriptor contains bit settings that mark this as a mouse event-generated GestureLinkquery instead of a keyboard-generated LinkActionRequest or client notification.

4

int

X - Horizontal map pixel location of event, from the top left corner.

4

int

Y - Vertical map pixel location of event from the top left corner.

4

int

Click count - number of times mouse button pressed and released at current location.

4

int

Modifiers for event, describing keyboard keys and mouse keys pressed.

4

float

Latitude, in decimal degrees, of event.

4

float

Longitude, in decimal degrees, of event.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

1

ASCII char

Tail marker describing the end of this section, or the end of the entire communication (END_SECTION or END_TOTAL)

Action Request for Key Events

# Bytes

Type

Description

4

ASCII char

<AR>

4

float

Version number of the action request format.

4

int

descriptor contains bit settings that mark this as a keyboard-generated LinkActionRequest instead of a mouse event-generated GestureLinkquery or client notification.

2

Unicode char

Keyboard character for event..

4

int

Modifiers for event, describing other keyboard keys pressed.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

1

ASCII char

Tail marker describing the end of this section, or the end of the entire communication (END_SECTION or END_TOTAL)

Action Request for Client Notification of Server Interest

# Bytes

Type

Description

4

ASCII char

<AR>

4

float

Version number of the action request format.

4

int

descriptor contains bit settings that mark this as a client notification instead of a mouse event-generated GestureLinkquery or keyboard-generated LinkActionRequest.

1

ASCII char

Tail marker describing the end of this section, or the end of the entire communication (END_SECTION or END_TOTAL)

The gesture descriptor is a masked integer that describes what kind of user event occured.

Gesture Descriptor Masking

Bit Number

Meaning

0

The mouse button was clicked (pressed and released).

1

Mouse button pressed.

2

Mouse button released.

3

Mouse was moved with no mouse buttons pressed.

4

Cursor entered the map area.

5

Cursor exited the map area.

6

Mouse moved with a mouse button down (dragged).

7

A keyboard key was pressed.

8

A keyboard key was released.

9

A graphic is involved in the gesture. For example, a mouse click occured on a graphic.

10

Client notification flag. This is set if the server is sending the query to let the client know what kind of gestures the server is interested in receiving.

11

Flag to set if the server should always be notified of a gesture, even if a graphic has responded to it on the client side. Since the graphics may contain properties that allow client actions to take place when a gesture occurs on a graphic, this flag indicates that a Action Request should also be sent to the server. Otherwise, the client determines what actions occur locally..

The modifier is a masked integer that describes if additional keyboard buttons where pressed down when the gesture occured.

Modifer Masking

Bit Number

Meaning

0

The Shift key on the keyboard was down.

1

The Control key on the keyboard was down.

2

The Meta key on the keyboard was down, or the mouse button #3 state changed.

3

The Alt key on the keyboard was down, or the mouse button #2 state changed.

4

The mouse button #1 state changed.

5

The Alt-Graph key state changed.



Description Definitions

Descriptions are sections that provide objects or actions across the link. They can be answers to queries, but they can also be sent to initiate communication. For example, a client can provide a list of graphics to be added to a repository on the server.. In general, if a client sends a query, it should expect some sort of description. If a descrition is sent, some sort of response should be expected. A 'No Action' response can be used as acknowledgement.

Graphics Description

A Graphics Description is the object that defines a list of graphics being sent over the link. The Graphics Description has a header to define the beginning of the list, and a tail to signify the end of it. The graphics in between have their own headers and definitions.

Graphics Description

# Bytes

Type

Description

3

ASCII char

<G>

4

float

Version number of the graphic list format.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Var

Graphics

A sequence of graphics, each with their own header and format.

1

ASCII char

Tail marker describing the end of this section, or the end of the entire communication (END_SECTION or END_TOTAL)


Actions

Actions are descriptions to Action Requests. There are a number of possible descriptions and any number of them can be included in this transmission. It should be assumed that the client will act on the descriptions in order.

Action List

# Bytes

Type

Description

3

ASCII char

<A>

4

float

Version number of the action list format.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Var

Actions

A sequence of actions, each with their own header and format.

1

ASCII char

Tail marker describing the end of this section, or the end of the entire communication (END_SECTION or END_TOTAL)


No Action Response

A No Action section is set when a client or server either doesn't know how to handle a query or definition set to it, or doesn't have anything else to say.

No Action

# Bytes

Type

Description

3

ASCII char

<?>

1

ASCII char

Tail marker describing the end of this section, or the end of the entire communication (END_SECTION or END_TOTAL)


Close Link Response

A Close Link response is sent when a client or server wants to sign off a link connection.

Close Link

# Bytes

Type

Description

3

ASCII char

<Q>

1

ASCII char

Tail marker describing the end of this section, or the end of the entire communication (END_SECTION or END_TOTAL)



Graphic Definitions

The graphic formats are defined below for Graphic and Gesture Descriptions. The green fields represent the fields in the protocol that change for each graphic depending on the render type of the graphic. The red fields represent the fields in the raster protocol that change depending on the image format of the raster.


Link Arc at Lat/Lon Location

# Bytes

Type

Description

3

ASCII char

<A>

1

byte

This space is for a graphic type identifier. For Arcs, the value is 10.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

4

float

Latitude of the arc's center, in decimal degrees.

4

float

Longitude of the arc's center, in decimal degrees.

4

float

Radius of the arc, in units defined in the next field.

1

byte

Units of the radius measurement. Values can be:
Decimal Degrees = -1
Kilometers = 0
Miles = 1
Nautical Miles = 2

4

int

Number of verticies to use to approximate the arc. If this value is -1, the projection algorithm of the client should decide the best value.

4

float

Starting angle of the arc, in decimal degrees. 0 is North, clockwise is positive.

4

float

Ending angle of the arc, in decimal degrees.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Arc at X/Y Location

# Bytes

Type

Description

3

ASCII char

<A>

1

byte

This space is for a graphic type identifier. For Arcs, the value is 10.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

4

int

Horizontal distance, from the left side of the map, of the arc's center, in pixels.

4

int

Vertical distance, from the top of the map, of the arc's center, in pixels.

4

int

Width of the arc, in pixels.

4

int

Height of the arc, in pixels.

4

float

Starting angle of the arc, in decimal degrees. 0 is North, clockwise is positive.

4

float

Ending angle of the arc, in decimal degrees.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Arc at X/Y Offset from Lat/Lon Location

# Bytes

Type

Description

3

ASCII char

<A>

1

byte

This space is for a graphic type identifier. For Arcs, the value is 10.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

4

float

Latitude of the arc's anchor point, in decimal degrees.

4

float

Longitude of the arc's anchor point, in decimal degrees.

4

int

Horizontal distance, from the longitude map anchor point location, of the arc's center, in pixels.

4

int

Vertical distance, from the latitude map anchor point location, of the arc's center, in pixels.

4

int

Width of the arc, in pixels.

4

int

Height of the arc, in pixels.

4

float

Starting angle of the arc, in decimal degrees. 0 is North, clockwise is positive.

4

float

Ending angle of the arc, in decimal degrees.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.


Link Bitmap at Lat/Lon Location

# Bytes

Type

Description

3

ASCII char

<B>

1

byte

This space is for a graphic type identifier. For Bitmaps, the value is 1.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

4

float

Latitude of the bitmap's upper left corner, in decimal degrees.

4

float

Longitude of the bitmap's upper left corner, in decimal degrees.

4

int

Width of the bitmap, in pixels.

4

int

Height of the bitmap, in pixels.

4

int

Number of bitmap bytes.

1n

byte

Bytes representing the bitmap.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Bitmap at X/Y Location

# Bytes

Type

Description

3

ASCII char

<B>

1

byte

This space is for a graphic type identifier. For Bitmaps, the value is 1.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

4

int

Horizontal distance, from the left side of the map, of the bitmap's upper left corner, in pixels.

4

int

Vertical distance, from the top of the map, of the bitmap's upper left corner, in pixels.

4

int

Width of the bitmap, in pixels.

4

int

Height of the bitmap, in pixels.

4

int

Number of bitmap bytes.

1n

byte

Bytes representing the bitmap.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Bitmap at X/Y Offset from Lat/Lon Location

# Bytes

Type

Description

3

ASCII char

<B>

1

byte

This space is for a graphic type identifier. For Bitmaps, the value is 1.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

4

float

Latitude of the bitmap's anchor point, in decimal degrees.

4

float

Longitude of the bitmap's anchor point, in decimal degrees.

4

int

Horizontal distance, from the longitude map anchor point location, of the bitmap's upper left corner, in pixels.

4

int

Vertical distance, from the latitude map anchor point location, of the bitmap's upper left corner, in pixels.

4

int

Width of the bitmap, in pixels.

4

int

Height of the bitmap, in pixels.

4

int

Number of bitmap bytes.

1n

byte

Bytes representing the bitmap.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.


Link Circle at Lat/Lon Location

# Bytes

Type

Description

3

ASCII char

<C>

1

byte

This space is for a graphic type identifier. For Circles, the value is 6.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

4

float

Latitude of the circle's center, in decimal degrees.

4

float

Longitude of the circle's center, in decimal degrees.

4

float

Radius of the circle, in units defined in the next field.

1

byte

Units of the radius measurement. Values can be:
Decimal Degrees = -1
Kilometers = 0
Miles = 1
Nautical Miles = 2

4

int

Number of verticies to use to approximate the circle. If this value is -1, the projection algorithm of the client should decide the best value.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Circle at X/Y Location

# Bytes

Type

Description

3

ASCII char

<C>

1

byte

This space is for a graphic type identifier. For Circles, the value is 6.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

4

int

Horizontal distance, from the left side of the map, of the circle's center, in pixels.

4

int

Vertical distance, from the top of the map, of the circle's center, in pixels.

4

int

Width of the circle, in pixels.

4

int

Height of the circle, in pixels.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Circle at X/Y Offset from Lat/Lon Location

# Bytes

Type

Description

3

ASCII char

<C>

1

byte

This space is for a graphic type identifier. For Circles, the value is 6.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

4

float

Latitude of the circle's anchor point, in decimal degrees.

4

float

Longitude of the circle's anchor point, in decimal degrees.

4

int

Horizontal distance, from the longitude map anchor point location, of the circle's center, in pixels.

4

int

Vertical distance, from the latitude map anchor point location, of the circle's center, in pixels.

4

int

Width of the circle, in pixels.

4

int

Height of the circle, in pixels.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.


Link Ellipse at Lat/Lon Location

# Bytes

Type

Description

3

ASCII char

<E>

1

byte

This space is for a graphic type identifier. For Ellipses, the value is 11.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

4

float

Latitude of the ellipse's center, in decimal degrees.

4

float

Longitude of the ellipse's center, in decimal degrees.

4

float

Major axis value of the ellipse, in units defined in the next field.

4

float

Minor axis value of the ellipse, in units defined in the next field.

1

byte

Units of the axis measurements. Values can be:
Decimal Degrees = -1
Kilometers = 0
Miles = 1
Nautical Miles = 2

4

float

Rotation angle in radians.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Ellipse at X/Y Location

# Bytes

Type

Description

3

ASCII char

<E>

1

byte

This space is for a graphic type identifier. For Ellipses, the value is 11.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

4

int

Horizontal distance, from the left side of the map, of the ellipse's center, in pixels.

4

int

Vertical distance, from the top of the map, of the ellipse's center, in pixels.

4

int

Major axis length of the ellipse, in pixels.

4

int

Minor axis length of the ellipse, in pixels.

4

float

Rotation angle in radians.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Ellipse at X/Y Offset from Lat/Lon Location

# Bytes

Type

Description

3

ASCII char

<E>

1

byte

This space is for a graphic type identifier. For Ellipses, the value is 11.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

4

float

Latitude of the ellipse's anchor point, in decimal degrees.

4

float

Longitude of the ellipse's anchor point, in decimal degrees.

4

int

Horizontal distance, from the longitude map anchor point location, of the ellipse's center, in pixels.

4

int

Vertical distance, from the latitude map anchor point location, of the ellipse's center, in pixels.

4

int

Width of the ellipse, in pixels.

4

int

Height of the ellipse, in pixels.

4

int

Width of the ellipse, in pixels.

4

int

Height of the ellipse, in pixels.

4

float

Rotation angle in radians.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.


The meaning of location attributes of the grid depend on the rendertype of the grid. Likewise, the direction of increasing rows also depends on the rendertype. The convention, howeverm is consistant. The rows and columns always increase according to the rendered background. For example, for Lat/Lon rendered grids, the latitude and longitude of the location of the grid refers to the lower right corner of the grid. The rows of the data increase as the latitude increases, and the columns increase with the longitudes. For X/Y and Offset rendertypes, the grid is located by the x/y point of the upper left corner of the grid. The rows increase as the y pixel count increases, which is actually down the screen. The column count increases with the x pixel count, which is to the right. The advantage of this is that the horizontal and vertical resolution directly apply to the index of the columns and rows, when mapping between lat/lon or x/y to the grid.

Link Grid at Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<GD>

1

byte

This space is for a graphic type identifier. For Grids, the value is 8.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

4

float

Latitude of the grid's lower left corner, in decimal degrees.

4

float

Longitude of the grid's lower left corner, in decimal degrees.

4

int

Number of vertical rows in the grid.

4

int

Number of horizontal columns in the grid.

4

float

Orientation of the grid, in radians. North is 0.0, where the columns are parallel to longitude lines.

4

float

Vertical resolution of the rows, in degrees/point.

4

float

Horizontal resolution of the columns, in degrees/point.

1

byte

Major dimension designation, indicating the primary dimension of the data. If the data is listed as columns this value is 0 (COLUMN_MAJOR). If the data is listed as rows, the value is 1 (ROW_MAJOR).

4

int

Number of integer values to follow. Should equal rows*columns.

Var

int

Integer data for the grid.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Grid at X/Y Location

# Bytes

Type

Description

4

ASCII char

<GD>

1

byte

This space is for a graphic type identifier. For Grids, the value is 8.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

4

int

Horizontal distance, from the left side of the map, of the grid's left side, in pixels.

4

int

Vertical distance, from the top of the map, of the grid's top, in pixels.

4

int

Number of vertical rows in the grid.

4

int

Number of horizontal columns in the grid.

4

float

Orientation of the grid, in radians. Up is 0.0, where the columns are parallel to the sides of the map.

4

float

Vertical resolution of the rows, in pixels/point.

4

float

Horizontal resolution of the columns, in pixels/point.

1

byte

Major dimension designation, indicating the primary dimension of the data. If the data is listed as columns this value is 0 (COLUMN_MAJOR). If the data is listed as rows, the value is 1 (ROW_MAJOR).

4

int

Number of integer values to follow. Should equal rows*columns.

Var

int

Integer data for the grid.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Grid at X/Y Offset from Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<GD>

1

byte

This space is for a graphic type identifier. For Grids, the value is 8.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

4

float

Latitude of the grid's anchor point, in decimal degrees.

4

float

Longitude of the grid's anchor point, in decimal degrees.

4

int

Horizontal distance, from the longitude map anchor point location, of the grid's left side, in pixels.

4

int

Vertical distance, from the latitude map anchor point location, of the grid's top, in pixels.

4

int

Number of vertical rows in the grid.

4

int

Number of horizontal columns in the grid.

4

float

Orientation of the grid, in radians. Up is 0.0, where the columns are parallel to the sides of the map.

4

float

Vertical resolution of the rows, in pixels/point.

4

float

Horizontal resolution of the columns, in pixels/point.

1

byte

Major dimension designation, indicating the primary dimension of the data. If the data is listed as columns this value is 0 (COLUMN_MAJOR). If the data is listed as rows, the value is 1 (ROW_MAJOR).

4

int

Number of integer values to follow. Should equal rows*columns.

Var

int

Integer data for the grid.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.


Link Line with Lat/Lon Endpoints

# Bytes

Type

Description

3

ASCII char

<L>

1

byte

This space is for a graphic type identifier. For Lines, the value is 4.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

1

byte

Line type definition. The possible values are:
Unknown line type = 0
Straight line = 1
Rhumb line (constant bearing) = 2
Great circle line = 3

4

float

Latitude of the line's start point, in decimal degrees.

4

float

Longitude of the line's start point, in decimal degrees.

4

float

Latitude of the line's end point, in decimal degrees.

4

float

Longitude of the line's end point, in decimal degrees.

4

int

Number of segments to use in approximating a curved line on the map. If the value is -1, the client's projection algorithm should determine the best value.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Line with X/Y Endpoints

# Bytes

Type

Description

3

ASCII char

<L>

1

byte

This space is for a graphic type identifier. For Lines, the value is 4.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

4

int

Horizontal distance, from the left side of the map, of the line's start point, in pixels.

4

int

Vertical distance, from the top of the map, of the line's start point, in pixels.

4

int

Horizontal distance, from the left side of the map, of the line's end point, in pixels.

4

int

Vertical distance, from the top of the map, of the line's end point, in pixels.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Line with X/Y EndPoints at Lat/Lon Location

# Bytes

Type

Description

3

ASCII char

<L>

1

byte

This space is for a graphic type identifier. For Lines, the value is 4.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

4

float

Latitude of the line's anchor point, in decimal degrees.

4

float

Longitude of the line's anchor point, in decimal degrees.

4

int

Horizontal distance, from the longitude map anchor point location, of the line's start point, in pixels.

4

int

Vertical distance, from the latitude map anchor point location, of the line's start point, in pixels.

4

int

Horizontal distance, from the longitude map anchor point location, of the line's end point, in pixels.

4

int

Vertical distance, from the latitude map anchor point location, of the line's end point, in pixels.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.


Link Point at a Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<PO>

1

byte

This space is for a graphic type identifier. For Points, the value is 9.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

4

float

Latitude of the point, in decimal degrees.

4

float

Longitude of the point, in decimal degrees.

4

float

Radius of the point, in pixels.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties. For Points, a oval=true property can be added to specify that the point should be rendered as a circle.

Link Point at a X/Y Location

# Bytes

Type

Description

4

ASCII char

<PO>

1

byte

This space is for a graphic type identifier. For Points, the value is 9.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

4

int

Horizontal distance, from the left side of the map, of the point's location, in pixels.

4

int

Vertical distance, from the top of the map, of the point's location, in pixels.

4

float

Radius of the point, in pixels.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties. For Points, a oval=true property can be added to specify that the point should be rendered as a circle.

Link Point at a X/Y Distance from a Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<PO>

1

byte

This space is for a graphic type identifier. For Points, the value is 9.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

4

float

Latitude of the point's anchor point, in decimal degrees.

4

float

Longitude of the point's anchor point, in decimal degrees.

4

int

Horizontal distance, from the longitude map anchor point location, of the point's location, in pixels.

4

int

Vertical distance, from the latitude map anchor point location, of the point's location, in pixels.

4

float

Radius of the point, in pixels.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties. For Points, a oval=true property can be added to specify that the point should be rendered as a circle.


Lat/Lon polygons, by definition, list their points in a clockwise direction.

Link Poly with Lat/Lon Points

# Bytes

Type

Description

4

ASCII char

<PY>

1

byte

This space is for a graphic type identifier. For Polys, the value is 3.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

1

byte

Line type definition. The possible values are:
Unknown line type = 0
Straight line = 1
Rhumb line (constant bearing) = 2
Great circle line = 3

4

int

Number of latitude and longitude values to follow. Each latitude and longitude value contributes to this count.

4n

float

Each float represents alternating latitude and longitude values, in decimal degrees.

1

byte

Units of the lat/lon values. Possibilities include:
Decimal degrees = 0
Radians = 1

4

int

Number of segments to use in approximating a curved poly on the map. If the value is -1, the client's projection algorithm should determine the best value.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Poly with X/Y Points

# Bytes

Type

Description

4

ASCII char

<PY>

1

byte

This space is for a graphic type identifier. For Lines, the value is 3.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

4

int

Number of x and y values to follow. Each x and y value contributes to this count.

4n

int

Each integer represents alternating x and y values, in pixels. The x value represents the horizontal number of pixels between the point and the left side of the map. The y value represents the vertical number of pixels between the point and the top of the map.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Poly with X/Y Points at Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<PY>

1

byte

This space is for a graphic type identifier. For Lines, the value is 3.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

4

float

Latitude of the poly's anchor point, in decimal degrees.

4

float

Longitude of the poly's anchor point, in decimal degrees.

4

int

Number of x and y values to follow. Each x and y value contributes to this count.

4n

int

Each integer represents alternating x and y values, in pixels. For the first point in the list, the x value represents the horizontal number of pixels between the first point and the anchor point location, while the y value represents the vertical pixel distance. The meaning of the remaining pixel values depends on the coordinate mode, described next.

1

byte

Coordinate mode of the x/y points. If the coordinate mode is from the origin, then all the x values refer to the horizontal pixel distance between the point and the first point, and the y values refer to the vertical pixel distance. If the mode is from the previous point, then all the measurements are taken from the point proceeding the current one. The possible values are:
origin = 0
previous = 1

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.


Link Raster

Images can be transmitted in three different formats. Two of these represent different colormodels, and the third format is indicates that the image can be downloaded from an URL. The direct colormodel is when the pixels are integers containing the RGB integer values. The indexed colormodel is when the pixels are bytes, and each byte refers to an index into a colortable. The colortable is an array of RGB integers.

Link Raster, Utilizing the Direct Colormodel, with Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<RA>

1

byte

This space is for a graphic type identifier. For Rasters, the value is 7.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

1

byte

Image format. This Raster is using the direct colormodel, and the value is 0.

4

float

Latitude of the upper left point of the image, in decimal degrees.

4

float

Longitude of the upper left point of the image, in decimal degrees.

4

int

Width of the image, in pixels.

4

int

Height of the image, in pixels.

4

int

Number of integer pixels in the image.

4n

int

Pixel values of the image, each representing a RGB integer value.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Raster, Utilizing the Direct Colormodel, with X/Y Points

# Bytes

Type

Description

4

ASCII char

<RA>

1

byte

This space is for a graphic type identifier. For Rasters, the value is 7.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

1

byte

Image format. This Raster is using the direct colormodel, and the value is 0.

4

int

Horizontal pixel offset, from the left side of the map, of the upper left corner of the image.

4

int

Vertical pixel offset, from the top of the map, of the top left corner of the image.

4

int

Width of the image, in pixels.

4

int

Height of the image, in pixels.

4

int

Number of integer pixels in the image.

4n

int

Pixel values of the image, each representing a RGB integer value.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Raster, Utilizing the Direct Colormodel, with X/Y Offset at Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<RA>

1

byte

This space is for a graphic type identifier. For Rasters, the value is 7.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

1

byte

Image format. This Raster is using the direct colormodel, and the value is 0.

4

float

Latitude of the raster's anchor point, in decimal degrees.

4

float

Longitude of the raster's anchor point, in decimal degrees.

4

int

Horizontal pixel offset, from the map location of the anchor point, of the upper left corner of the image.

4

int

Vertical pixel offset, from the map location of the anchor point, of the upper left corner of the image.

4

int

Width of the image, in pixels.

4

int

Height of the image, in pixels.

4

int

Number of integer pixels in the image.

4n

int

Pixel values of the image, each representing a RGB integer value.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Raster, Utilizing the Indexed Colormodel, with Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<RA>

1

byte

This space is for a graphic type identifier. For Rasters, the value is 7.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

1

byte

Image format. This Raster is using the indexed colormodel, and the value is 1.

4

float

Latitude of the upper left point of the image, in decimal degrees.

4

float

Longitude of the upper left point of the image, in decimal degrees.

4

int

Width of the image, in pixels.

4

int

Height of the image, in pixels.

4

int

Number of bytes to create the Raster.

1n

byte

Array of bytes used to create bitmap.

4

int

Number of integers to create the colortable.

4n

int

Array of RGB integers that represent the colortable.

4

int

The transparency of the image. This should be a value between 0-255, where 255 means an opaque image.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Raster, Utilizing the Indexed Colormodel, with X/Y Points

# Bytes

Type

Description

4

ASCII char

<RA>

1

byte

This space is for a graphic type identifier. For Rasters, the value is 7.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

1

byte

Image format. This Raster is using the indexed colormodel, and the value is 1.

4

int

Horizontal pixel offset, from the left side of the map, of the upper left corner of the image.

4

int

Vertical pixel offset, from the top of the map, of the top left corner of the image.

4

int

Width of the image, in pixels.

4

int

Number of bytes to create the image.

1n

byte

Array of bytes used to create image.

4

int

Number of integers to create the colortable.

4n

int

Array of RGB integers that represent the colortable.

4

int

The transparency of the image. This should be a value between 0-255, where 255 means an opaque image.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Raster, Utilizing the Indexed Colormodel, with X/Y Offset at Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<RA>

1

byte

This space is for a graphic type identifier. For Rasters, the value is 7.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

1

byte

Image format. This Raster is using the indexed colormodel, and the value is 1.

4

float

Latitude of the raster's anchor point, in decimal degrees.

4

float

Longitude of the raster's anchor point, in decimal degrees.

4

int

Horizontal pixel offset, from the map location of the anchor point, of the upper left corner of the image.

4

int

Vertical pixel offset, from the map location of the anchor point, of the upper left corner of the image.

4

int

Width of the image, in pixels.

4

int

Height of the image, in pixels.

4

int

Number of bytes to create the Raster.

1n

byte

Array of bytes used to create bitmap.

4

int

Number of integers to create the colortable.

4n

int

Array of RGB integers that represent the colortable.

4

int

The transparency of the image. This should be a value between 0-255, where 255 means an opaque image.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Raster, Referencing an Image URL, with Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<RA>

1

byte

This space is for a graphic type identifier. For Rasters, the value is 7.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

1

byte

Image format. This Raster is referencing an URL, and the value is 2.

4

float

Latitude of the upper left point of the image, in decimal degrees.

4

float

Longitude of the upper left point of the image, in decimal degrees.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties. The URL of the image to use is located in the Arg List.

Link Raster, Referencing an URL, with X/Y Points

# Bytes

Type

Description

4

ASCII char

<RA>

1

byte

This space is for a graphic type identifier. For Rasters, the value is 7.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

1

byte

Image format. This Raster is referencing an URL, and the value is 2.

4

int

Horizontal pixel offset, from the left side of the map, of the upper left corner of the image.

4

int

Vertical pixel offset, from the top of the map, of the top left corner of the image.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.. The URL of the image to use is located in the Arg List.

Link Raster, Referencing an URL, with X/Y Offset at Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<RA>

1

byte

This space is for a graphic type identifier. For Rasters, the value is 7.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

1

byte

Image format. This Raster is referencing an URL, and the value is 2.

4

float

Latitude of the raster's anchor point, in decimal degrees.

4

float

Longitude of the raster's anchor point, in decimal degrees.

4

int

Horizontal pixel offset, from the map location of the anchor point, of the upper left corner of the image.

4

int

Vertical pixel offset, from the map location of the anchor point, of the upper left corner of the image.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.. The URL of the image to use is located in the Arg List.


Link Rectangle with Lat/Lon Corners

# Bytes

Type

Description

4

ASCII char

<RE>

1

byte

This space is for a graphic type identifier. For Rectangles, the value is 5.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

1

byte

Line type definition. The possible values are:
Unknown line type = 0
Straight line = 1
Rhumb line (constant bearing) = 2
Great circle line = 3

4

float

Latitude of the rectangle's Northwest corner, in decimal degrees.

4

float

Longitude of the rectangle's Northwest corner, in decimal degrees.

4

float

Latitude of the rectangle's Southeast corner, in decimal degrees.

4

float

Longitude of the rectangle's Southeast corner, in decimal degrees.

4

int

Number of segments to use in approximating a curved rectangle on the map. If the value is -1, the client's projection algorithm should determine the best value.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Rectangle with X/Y Corners

# Bytes

Type

Description

4

ASCII char

<RE>

1

byte

This space is for a graphic type identifier. For Rectangles, the value is 5.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

4

int

Horizontal distance, from the left side of the map, of the rectangle's upper left corner, in pixels.

4

int

Vertical distance, from the top of the map, of the rectangle's upper left corner, in pixels.

4

int

Horizontal distance, from the left side of the map, of the rectangle's lower right corner, in pixels.

4

int

Vertical distance, from the top of the map, of the rectangle's lower right corner, in pixels.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.

Link Rectangle with X/Y Corners at Lat/Lon Location

# Bytes

Type

Description

4

ASCII char

<RE>

1

byte

This space is for a graphic type identifier. For Rectangles, the value is 5.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

4

float

Latitude of the rectangle's anchor point, in decimal degrees.

4

float

Longitude of the rectangle's anchor point, in decimal degrees.

4

int

Horizontal distance, from the longitude map anchor point location, of the rectangle's upper left corner, in pixels.

4

int

Vertical distance, from the latitude map anchor point location, of the rectangle's upper left corner, in pixels.

4

int

Horizontal distance, from the longitude map anchor point location, of the rectangle's lower right corner, in pixels.

4

int

Vertical distance, from the latitude map anchor point location, of the rectangle's lower right corner, in pixels.

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties.


Text is anchored to a specified point on the map using the baseline of the text. The justification parameter of the text determines the left-to-right location of the charaters on the baseline.

Link Text at Lat/Lon Location

# Bytes

Type

Description

3

ASCII char

<T>

1

byte

This space is for a graphic type identifier. For Text, the value is 2.

1

byte

This space is for a Rendertype identifier. For Lat/Lon rendering, the value is 1.

4

float

Latitude of the text, in decimal degrees.

4

float

Longitude of the text, in decimal degrees.

1

byte

Justification of text with regard to the Lat/Lon point. Possible values:
left = 0
center = 1
right = 2

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties. The text string and the font representation string are located in the Arg List.

Link Text at X/Y Location

# Bytes

Type

Description

3

ASCII char

<T>

1

byte

This space is for a graphic type identifier. For Text, the value is 5.

1

byte

This space is for a Rendertype identifier. For X/Y rendering, the value is 2.

4

int

Horizontal distance, from the left side of the map, of the text, in pixels.

4

int

Vertical distance, from the top of the map, of the text, in pixels.

1

byte

Justification of text with regard to the Lat/Lon point. Possible values:
left = 0
center = 1
right = 2

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties. The text string and the font representation string are located in the Arg List.

Link Text with X/Y Offset at Lat/Lon Location

# Bytes

Type

Description

3

ASCII char

<T>

1

byte

This space is for a graphic type identifier. For Text, the value is 2.

1

byte

This space is for a Rendertype identifier. For offset rendering, the value is 3.

4

float

Latitude of the text's anchor point, in decimal degrees.

4

float

Longitude of the text's anchor point, in decimal degrees.

4

int

Horizontal distance, from the longitude map anchor point location, of the text, in pixels.

4

int

Vertical distance, from the latitude map anchor point location, of the text, in pixels.

1

byte

Justification of text with regard to the Lat/Lon point. Possible values:
left = 0
center = 1
right = 2

Var

Arg List

A list of key-value pairs for attribute passing. See Defined Properties. The text string and the font representation string are located in the Arg List.


Defined Properties

The properties can contain information on how a graphic should be drawn, or describing an action that the client should take. In addition to these defined property names, any other property may be defined and passed across the link.

RGB Integers are used in the protocol to describe colors. The colors should be passed as hex string representations of the desiired color. Bits 23-16 represent the red value, bits 15-8 represent the green value, and bits 7-0 represent the blue value. The range of values in each color byte is 0 (weakest) to 255 (strongest). For system implementations that support it, bits 31-24 represent a tranparency value, where 255 is opaque. For instance, a color representation of an opaque red should be passed as FFFF0000.

Link Properties

Property Name

Meaning

lc

Property key describing the RGB Integer for the line color.

hc

Property key describing the RGB Integer for the highlight line color.

fc

Property key describing the RGB Integer for the fill color.

lw

Property key describing the integer for the line width.

ts

Property key describing the content string for LinkText objects.

tf

Property key describing the font description string for LinkText objects.

rot

Property key describing the amount of rotation for LinkGraphics that support rotation, like LinkText and LinkRaster objects.

tbl

Property key describing the location of the baseline for LinkText objects (BASELINE_BOTTOM, BASELINE_MIDDLE or BASELINE_TOP. BOTTOM is the default).

riu

Property key describing the URL of an image that a LinkRaster would use if configured to do that.

gid

Property key describing graphic identifier for a Link Graphic object.

url

Property key describing a url to be used for a list or object.

html

Property key describing html text to be displayed for a list or object.

info

Property key describing a short message to be displayed for a list or object.

mess

Property key describing text for a pop-up window or other messaging tool for be used for a list or object.

time

Property key describing a time entry.

lat

Property key describing the decimal degree latitude for a projection definition (Server directed).

lon

Property key describing the decimal degree longitude for a projection definition (Server directed).

s

Property key describing the scale for a projection definition (Server directed).

w

Property key describing the pixel width of a projection definition (Server directed).

h

Property key describing the pixel height of a projection definition (Server directed).

p

Property key describing the projection type of a projection definition (Server directed).

latmin

Property key describing the lower latitude in decimal degrees of a projection definition (Server directed).

lonmin

Property key describing the westward longitude in decimal degrees of a projection definition (Server directed).

latmax

Property key describing the upper latitude in decimal degrees of a projection definition (Server directed).

lonmax

Property key describing the eastward longitude in decimal degrees of a projection definition (Server directed).

S

Property value describing the solid line style.

LD

Property value describing the long dash line style.

DA

Property value describing the dash line style.

D

Property value describing the dot line style.

DAD

Property value describing the dash-dot line style.

DADD

Property value describing the dash-dot-dot line style.

S

Property value describing the solid fill pattern.

V

Property value describing the vertical stripe fill pattern.

H

Property value describing the horizontal stripe fill pattern.

C

Property value describing the cross-hatch fill pattern.

DC

Property value describing the diagonal cross-hatch fill pattern.

FD

Property value describing the forward diagonal cross fill pattern.

BD

Property value describing the backward diagonal cross fill pattern.



Action Definitions

Actions are tasks that the server gives to the client in order to manipulate graphics as a result of user gestures or to display updated data.


A Graphic action is the server requesting that the client update the appearance of some or all of the graphics on the map. Any part of the graphic can be modified, and the protocol also supports the addition and deletion of graphics.

Graphic Action

# Bytes

Type

Description

4

ASCII char

<UG>

1

byte

Action identifier. For graphic actions, the value is 0

4

int

Graphic action descriptor, which is a masked integer that describes the action to be taken on the graphic.

Var

Graphic or Arg List, depending on the graphic action descriptor.

If the graphic action descriptor describes an action that requires more information about the updates on a specific graphic, the graphic is included here. Otherwise, a graphic ID property is included in the Arg List

The graphic action descriptor is a masked integer that describes what action should be taken on a graphic. Many actions can be described with the descriptor. For example, a graphic may be raised and selected at the same time. The two actions that require a graphics object are adding a graphic, and updating a graphic.

Graphic Action Descriptor Masking

Bit Number

Meaning

0

Raise the graphic to be on top of all the other graphics supplied by the server.

1

Lower the graphic to be under all the other graphics supplied by the server.

2

Delete the graphic.

3

Select the graphic.

4

Deselect the graphic.

5

Deselect all the graphics.

6

Add the graphic. This requires a graphic description.

7

Update the graphic. This requires a graphic description.


A Map Update action is the server requesting that the client update the location (projection) of a map.

Map Update

# Bytes

Type

Description

4

ASCII char

<UM>

1

byte

Action identifier. For graphic actions, the value is 2.

Var

Arg List

The Arg List set of properties which describe the new map projection parameters, including center latitude and longitude, scale, projection type and pixel size. See the Defined Properties.


Args are an array of strings which represent key-value pairs. As of version 0.6, the args may contain a key-value pair at the start of the list that advises if these args should overwrite the last set of args (reuse) or be read without memory of previous args (clear). This key-value pair is optional.

Link Args

# Bytes

Type

Description

4

int

Sum of the number of keys and values.

The key-value pairs follow:

4

int

Length of key (1) for management policy (to reuse or clear any buffered properties).

1

byte

Text representing management policy key, or 'p'.

4

int

Length of value (1) for management policy setting.

1

byte

Text representing management policy value ('R' to reuse, 'C' to clear).

4

int

Length of text (key or value), number of characters.

2n

Unicode char

Text representing key or value.


OpenMap
Last modified: Mon Feb 9 15:29:07 EST 2004