Constants:

• PDU_HEADER_LENGTH 6
• PDU_MAX_FRAG_SIZE 0×3FFF
• PDU_MAX_PAYLOAD_SIZE (PDU_MAX_FRAG_SIZE – PDU_HEADER_LENGTH)

SHARED_PDU_HEADER
{
uint16 channel;
uint8 pduType;
uint8 fragFlags;
uint16 fragSize;
};

channel (2 bytes):

• PDU_CHANNEL_SESSION 0×00
• PDU_CHANNEL_SURFACE 0×01
• PDU_CHANNEL_INPUT 0×02

pduType (1 byte): Channel-specific PDU type

fragFlags (1 byte):

• PDU_FRAGMENT_SINGLE 0×00
• PDU_FRAGMENT_FIRST 0×01
• PDU_FRAGMENT_NEXT 0×02
• PDU_FRAGMENT_LAST 0×03

fragSize (2 bytes):

Size of the current fragment payload, including the PDU header. The maximum value for fragSize is 0×3FFF.

pduType:

• PDU_SESSION_JOIN_REQ 0×01
• PDU_SESSION_LEAVE_REQ 0×02
• PDU_SESSION_CREATE_REQ 0×03
• PDU_SESSION_TERM_REQ 0×04
• PDU_SESSION_AUTH_REQ 0×05
• PDU_SESSION_NOTIFY_REQ 0×06
• PDU_SESSION_LIST_REQ 0×0A
• PDU_SESSION_JOIN_RSP 0×81
• PDU_SESSION_LEAVE_RSP 0×82
• PDU_SESSION_CREATE_RSP 0×83
• PDU_SESSION_TERM_RSP 0×84
• PDU_SESSION_AUTH_RSP 0×85
• PDU_SESSION_NOTIFY_RSP 0×86
• PDU_SESSION_LIST_RSP 0×8A

SESSION_SHARED_KEY { char¹² };

The Session Shared Key is a 12-character string consisting only of uppercase alphanumeric characters. It is a non null-terminated ASCII string of 12 characters, with a fixed size of 12 bytes.

Sample Session Shared Keys:

• 9HDKW3X67LBZ
• JD74KPR31YTR
• 5HB14NQ83IHW

Session Shared Keys uniquely identify a screencasting session.

SESSION_ID { uint32 };

The Session ID is an unsigned integer of 32 bits. It uniquely identifies a client session. One client may have multiple Session IDs if it participates in more than one screencasting session at the same time.

SESSION_STATUS { uint32 };

The Session Status is an unsigned integer of 32 bits indicating the status of a request. 0 indicates success, while non-zero values indicate an error.

SESSION_USER_ID
{
uint16 usernameLength;
char* username;
};

The Session User ID is a data structure used by clients within a session to uniquely identify themselves. Since the identifier consists of the username of a client, it is not possible for two clients to be connected within the same session with the same username.

SESSION_USER
{
SESSION_USER_ID id;
uint16 privilegeflags;
};

The Session User is a data structure containing a SESSION_USER_ID along with descriptive information regarding the user, such as privileges.

The Session Request PDU Header (10 bytes) is shared by all Session Request PDUs.

SESSION_REQ_HEADER
{
SHARED_PDU_HEADER sharedHeader;
SESSION_ID sessionId;
};

The Session Response PDU Header (14 bytes) is shared by all Session Response PDUs.

SESSION_RSP_HEADER
{
SHARED_PDU_HEADER sharedHeader;
SESSION_ID sessionId;
SESSION_STATUS sessionStatus;
};

The Session Join Request PDU is sent by the client to request to join an existing session using a Session Shared Key.

SESSION_JOIN_REQ_PDU
{
SESSION_REQ_PDU_HEADER sessionHeader;
SESSION_SHARED_KEY sessionKey;
};

sessionHeader: pduType MUST be set to PDU_SESSION_JOIN_REQ (0×01). Session ID SHALL be set to 0.

sessionKey: Session Shared Key specified earlier. This protocol does not define how the Session Shared Key is initially shared, it is up to the session initiator to use proper communication channels to invite participants and provide them with the key.

The Session Join Response PDU is sent from server to client in response to a Session Join Request.

SESSION_JOIN_RSP_PDU
{
SESSION_RSP_PDU_HEADER sessionHeader;
SESSION_SHARED_KEY sessionKey;
uint8 sessionFlags;
};

sessionHeader: pduType MUST be set to PDU_SESSION_JOIN_RSP (0×81). if successful, Session ID assigned by the server to the client. The client MUST cache this Session ID for the life time of the session.

sessionKey: MUST be the same key as the one originally sent by the client in the corresponding Session Join Request PDU.

sessionFlags: flags describing the session to join:

• SESSION_FLAGS_PASSWORD_PROTECTED 0×01

The Session Leave Request PDU is sent by the client to request to leave a previously joined session.

SESSION_LEAVE_REQ_PDU
{
SESSION_REQ_PDU_HEADER sessionHeader;
};

sessionHeader: pduType MUST be set to PDU_SESSION_LEAVE_REQ (0×02). Session ID identifies the client session to leave.

The Session Leave Response PDU is sent from server to client in response to a Session Leave Request PDU.

SESSION_LEAVE_RSP_PDU
{
SESSION_RSP_PDU_HEADER sessionHeader;
};

sessionHeader: pduType MUST be set to PDU_SESSION_LEAVE_RSP (0×82). If successful, Session ID MUST be the same as the Session ID originally sent by the client.

The Session Create Request PDU is sent by the client (session initiator) to request a new screencasting session to be created on the server.

SESSION_CREATE_REQ_PDU
{
SESSION_REQ_PDU_HEADER sessionHeader;
uint16 usernameLength;
uint16 passwordLength;
char* username;
char* password;
};

sessionHeader: pduType MUST be set to PDU_SESSION_CREATE_REQ (0×03). Session ID SHALL be set to 0.

usernameLength: length of the username field in bytes.

passwordLength: length of the password field in bytes.

username: non null-terminated ASCII string, username of the session initiator.

password: non null-terminated ASCII string, optional password to be used for restricting access to the screencasting session.

The Session Create Response PDU is sent by the server in response to a Session Create Request PDU, and provides the Session Shared Key to the Session Initiator.

SESSION_CREATE_RSP_PDU
{
SESSION_RSP_PDU_HEADER sessionHeader;
SESSION_SHARED_KEY sessionKey;
};

sessionHeader: pduType MUST be set to PDU_SESSION_CREATE_RSP (0×83). The Session ID provided is to be used by the session initiator for subsequent requests, similar to the Session ID provided as a result of a Session Join Request.

sessionKey: new Session Shared Key to be shared with participants, enabling them to join the newly created screencasting session.

The Session Termination Request PDU is sent by the client (session controller) to request that a screencasting session be terminated, disconnecting all session participants.

SESSION_TERM_REQ_PDU
{
SESSION_REQ_PDU_HEADER sessionHeader;
SESSION_SHARED_KEY sessionKey;
};

sessionHeader: pduType MUST be set to PDU_SESSION_TERM_REQ (0×04). Session ID is the one used by the client within the screencasting session identified by the Session Shared Key. The Session Shared Key identifies the screencasting session to terminate.

sessionKey: Session Shared Key for the session to terminate.

The Session Termination Response PDU is sent the server to the requesting client only in the case of failure, otherwise it is sent to all session participants as a notification of session termination.

SESSION_TERM_RSP_PDU
{
SESSION_RSP_PDU_HEADER sessionHeader;
SESSION_SHARED_KEY sessionKey;
};

sessionHeader: pduType MUST be set to PDU_SESSION_TERM_RSP (0×84). If status is set to success, indicates a session termination notification. Otherwise, the Session Termination Response is only sent back to the requesting client with a status code describing the error.

sessionKey: Session Shared Key of the screencasting session that is being terminated, or requested to be terminated.

The Session Authenticate Request PDU is sent by the client following the reception of a successful Session Join Response.

SESSION_AUTH_REQ_PDU
{
SESSION_REQ_PDU_HEADER sessionHeader;
uint16 usernameLength;
uint16 passwordLength;
char* username;
char* password;
};

sessionHeader: pduType MUST be set to PDU_SESSION_AUTH_REQ (0×05).

usernameLength: length of the username field in bytes.

passwordLength: length of the password field in bytes. If the screencasting session does not require a password, this field MUST be set to zero.

username: non null-terminated ASCII string of variable length specified by the usernameLength field.

password: non null-terminated ASCII string of variable length specified by the passwordLength field.

The Session Authenticate Response PDU is sent by the server in response to a Session Authenticate Request PDU. If successful, the client completed the authentication sequence, otherwise a status code describing the error is provided.

SESSION_AUTH_RSP_PDU
{
SESSION_RSP_PDU_HEADER sessionHeader;
};

sessionHeader: pduType MUST be set to PDU_SESSION_AUTH_RSP (0×85).

The Session Notify Request PDU is sent by the server to connected clients for event notifications such as client connections or disconnections.

SESSION_JOIN_REQ_PDU
{
SESSION_REQ_PDU_HEADER sessionHeader;
uint16 notificationId;
SESSION_USER user;
uint16 messageLength;
char* message;
};

sessionHeader: pduType MUST be set to PDU_SESSION_NOTIFY_REQ (0×06).

notificationId:

• USER_CONNECTION:0×0001
• USER_DISCONNECTION: 0×0002

user: user for which the notification applies

messageLength: length of a notification message

message: descriptive human-readable notification message (optional). If omitted, messageLength MUST be set to 0.

The Session Notify Response PDU is sent by the client in response to a Session Notify Request PDU. This message is currently unused since no current notification type requires an explicit response from the client. It is reserved for future use.

SESSION_AUTH_RSP_PDU
{
SESSION_RSP_PDU_HEADER sessionHeader;
};

sessionHeader: pduType MUST be set to PDU_SESSION_LIST_RSP (0×86).

The Session List Request PDU is sent by the client to request to the list of users within the current screencasting session.

SESSION_JOIN_REQ_PDU
{
SESSION_REQ_PDU_HEADER sessionHeader;
};

sessionHeader: pduType MUST be set to PDU_SESSION_LIST_REQ (0×0A).

The Session List Response PDU is sent by the server in response to a Session List Request PDU. If successful, a list of users is given, otherwise a status code describing the error is provided.

SESSION_AUTH_RSP_PDU
{
SESSION_RSP_PDU_HEADER sessionHeader;
uint16 userCount;
SESSION_USER* users;
};

sessionHeader: pduType MUST be set to PDU_SESSION_LIST_RSP (0×8A).

userCount: the number of users in the list.

users: an array of SESSION_USER structures representing users, of length determined by the userCount field.

pduType:

• PDU_SURFACE_COMMAND 0×01

The Surface Message PDU Header (6 bytes) is shared by all Surface Message PDUs.

SURFACE_MSG_HEADER
{
SHARED_PDU_HEADER sharedHeader;
SESSION_ID sessionId;
};

SURFACE_COMMAND
{
uint16 destLeft;
uint16 destTop;
uint16 destRight;
uint16 destBottom;
uint8 bpp;
uint8 codecID;
uint16 width;
uint16 height;
uint32 bitmapDataLength;
uint8* bitmapData;
};

The Surface Message PDU is sent by the client when in sender mode, and is sent by the server when broadcasting. There is no difference between the format of the message being sent from client to server and the one sent from server to client.

SURFACE_MSG_PDU
{
SURFACE_MSG_HEADER surfaceMsgHeader;
SURFACE_COMMAND surfaceCommand;
};

surfaceCommand: a surface command.

pduType:

• PDU_INPUT_KEYBOARD 0×01
• PDU_INPUT_MOUSE 0×02

The Input Event PDU Header (6 bytes) is shared by all Input Event PDUs.

INPUT_EVT_HEADER
{
SHARED_PDU_HEADER sharedHeader;
SESSION_ID sessionId;
};

INPUT_KEYBOARD_PDU
{
INPUT_EVT_HEADER inputEventHeader;
uint16 keyboardFlags;
uint16 keyCode;
};

keyboardFlags:

• KBD_FLAGS_EXTENDED 0×0100
• KBD_FLAGS_DOWN 0×4000
• KBD_FLAGS_RELEASE 0×8000

keyCode: scancode of the key

INPUT_MOUSE_PDU
{
INPUT_EVT_HEADER inputEventHeader;
uint16 pointerFlags;
uint16 xPos;
uint16 yPos;
};

pointerFlags:

• PTR_FLAGS_MOVE 0×0800 mouse motion
• PTR_FLAGS_DOWN 0×8000 button press
• PTR_FLAGS_BTN1 0×1000 button 1 (left)
• PTR_FLAGS_BTN2 0×2000 button 2 (right)
• PTR_FLAGS_BTN3 0×4000 button 3 (middle)

xPos: x coordinate relative to the top left corner of the desktop’s window
yPos: y coordinate relative to the top left corner of the desktop’s window