361 lines
12 KiB
C
361 lines
12 KiB
C
/*******************************************************************
|
|
* Pilot Software
|
|
*
|
|
* Copyright (c) 1995-1997, Palm Computing Inc., All Rights Reserved
|
|
*
|
|
*-------------------------------------------------------------------
|
|
* FileName:
|
|
* CMCommon.h
|
|
*
|
|
* Description:
|
|
* Connection Management Protocol common definitions.
|
|
*
|
|
* History:
|
|
* 9/14/95 vmk Created by Vitaly Marty Kruglikov
|
|
* 11/19/96 vmk Added CM v1.1 receive timeout override extensions
|
|
*
|
|
*******************************************************************/
|
|
|
|
|
|
#ifndef __CM_COMMON_H__
|
|
#define __CM_COMMON_H__
|
|
|
|
#if EMULATION_LEVEL == 1 // EMULATION_WINDOWS
|
|
|
|
// Pilot common definitions
|
|
#include "Common.h"
|
|
|
|
#else // EMULATION_LEVEL != EMULATION_WINDOWS
|
|
|
|
// Pilot common definitions
|
|
#include <Common.h>
|
|
|
|
#endif // EMULATION_LEVEL == EMULATION_WINDOWS
|
|
|
|
#if EMULATION_WINDOWS != 1
|
|
LOGIC ERROR
|
|
#endif
|
|
|
|
|
|
|
|
/********************************************************************
|
|
* CMP 1.0 Command Format
|
|
********************************************************************/
|
|
|
|
// IT IS ANTICIPATED THAT the 1.0 PACKET FORMAT WILL BE USED TO INITIATE
|
|
// HOT SYNC "WAKE-UP" MESSAGE INDEFINITELY. BASED ON THE COMMUNICATIONS
|
|
// VERSION NUMBER PROVIDED IN THIS BASIC COMMAND STRUCTURE, FUTURE VERSIONS
|
|
// OF DESKTOP AND PILOT SOFTWARE MAY SUPPORT ADDITIONAL CONNECTION MANAGEMENT
|
|
// COMMANDS/FEATURES AS THE NEED ARISES. FOR EXAMPLE, TCP-ENABLED HOTSYNCS
|
|
// MAY PROVIDE ADDITIONAL INFORMATION, SUCH AS THE INTERNET ADDRESS OF THE
|
|
// PREFERRED HOTSYNC PC. THIS DESIGN PROVIDES FOR BACKWARD COMPATIBILITY
|
|
// WITH OLDER VERSIONS OF THE SOFTWARE. FUTURE COMMANDS WILL BE ADDED
|
|
// FOLLOWING THIS BASIC COMMAND SET.
|
|
|
|
// The CMP packets are used for transmitting data for the Pilot CMP protocol layer.
|
|
// The structure of the CMP packet is built into the data part of the SLP packet and is,
|
|
// therefore, constrained by the SLP packet data size limitations.
|
|
|
|
|
|
// Packet type values used in the CMP packet body "type" field:
|
|
//
|
|
typedef enum CmpType {
|
|
cmpWakeup = 1, // CMP Wakeup packet sent from server to client
|
|
cmpInit, // CMP Init packet sent from client to server
|
|
cmpAbort, // CMP Abort packet sent from client to server
|
|
cmpExtended // For future command extensions
|
|
} CmpType;
|
|
|
|
|
|
// cmpInit and cmpWakeup packet body structure:
|
|
//
|
|
typedef struct CmpBodyType {
|
|
Byte type; // CMP packet type
|
|
|
|
Byte flags; // in cmpInit packets: indicates which values were adjusted by
|
|
// the client(defined below); in cmpWakeup pakcets: null;
|
|
// in cmpAbort packets: reason for abort.
|
|
|
|
Byte verMajor; // Major PAD version number
|
|
Byte verMinor; // Minor PAD version number
|
|
Word wReserved; // RESERVED -- set to NULL!!!
|
|
//DWord commVersion; // in cmpWakeup: server comm software version number;
|
|
// in cmpInit: client comm version
|
|
|
|
DWord baudRate; // in cmpWakeup: max server baud rate;
|
|
// in cmpInit packets: the prescribed baud rate
|
|
} CmpBodyType;
|
|
|
|
typedef CmpBodyType* CmpBodyPtr;
|
|
|
|
// Flags used in the packet body "flags" field of cmpInit
|
|
// packets. These values are additive in the sense that they can be
|
|
// added or or'ed to form a composite value:
|
|
#define cmpInitFlagChangeBaudRate 0x80 // signals that the baud rate was adjusted by the client
|
|
|
|
// CM v1.1 extensions
|
|
#define cmpInitFlagRcvTOut1Min 0x40 // instructs the Pilot to set its receive timeout to 1 minute
|
|
#define cmpInitFlagRcvTOut2Min 0x20 // instructs the Pilot to set its receive timeout to 1 minute
|
|
|
|
|
|
// Flags used in the packet body "flags" field of cmpAbort packets.
|
|
// These values are additive in the sense that they can be
|
|
// added or or'ed to form a composite value:
|
|
#define cmpAbortFlagVersionError 0x80 // signals incompatible comm versions
|
|
|
|
|
|
|
|
/********************************************************************
|
|
* CMP Protocol Parameters
|
|
********************************************************************/
|
|
|
|
// This transaction id is used by cmpWakeup packets. cmpInit and cmpAbort
|
|
// packets MUST use a different transaction id.
|
|
//
|
|
#define cmpWakeupTransactionID 0xFF
|
|
|
|
// This is the baud rate at which CMP connections are initiated
|
|
//
|
|
#define cmpInitialBaudRate 9600L
|
|
|
|
// This is the time limit for trying to initiate a connection
|
|
//
|
|
#define cmpMaxInitiateSec 20
|
|
|
|
|
|
/********************************************************************
|
|
* CMP v2.0 Extensible Command Format
|
|
********************************************************************/
|
|
|
|
// THE v2.0 COMMANDS USE A MORE FLEXIBLE STRUCTURE TO ANTICIPATE DYNAMIC
|
|
// ADDITION OF NEW ARGUMENTS. THE COMMAND HEADER AND ARGUMENT IDENTIFIERS
|
|
// AND THEIR STRUCTURES WILL BE SPECIFIED IN THIS INCLUDE FILE. THE PACKAGING
|
|
// OF THE ARGUMENTS WILL BE SPECIFIED IN THE TRANSPORT IMPLEMENTATION
|
|
// WHICH PROVIDES THE UTILITY ROUTINES TO PACKAGE DYNAMIC ARGUMENTS.
|
|
|
|
typedef struct CmpCommandHeaderType {
|
|
Byte hdrType; // set to cmpExtended
|
|
Byte cmd; // extended command/response id
|
|
Word errorCode; // used in replies; set to null in commands!
|
|
Byte argCount; // number of arguments
|
|
Byte reserved1; // RESERVED - SET TO NULL!
|
|
DWord reserved2; // RESERVED - SET TO NULL!
|
|
} CmpCommandHeaderType;
|
|
|
|
|
|
// Generic command type for
|
|
typedef union CmpGenericCommandType {
|
|
Byte hdrType; // command header type(CmpType)
|
|
CmpBodyType body10; // v1.0 command/response body
|
|
CmpCommandHeaderType exHdr; // v2.0 extended command/response header
|
|
} CmpGenericCommandType;
|
|
|
|
typedef CmpGenericCommandType* CmpGenericCommandPtr;
|
|
|
|
|
|
// cmpRespBit is used to form a response ID from a
|
|
// command ID by or'ing it with the function ID.
|
|
#define cmpRespBit 0x80
|
|
|
|
// cmpCmdIDMask is used to mask out the command/response ID value
|
|
#define cmpCmdIDMask 0x7f
|
|
|
|
// Command/Response argument id's begin at this value
|
|
#define cmpFirstArgID 0x20
|
|
|
|
|
|
//-------------------------------------------------------------------------
|
|
// Connection Management error codes returned in the response errorCode
|
|
// field.
|
|
//-------------------------------------------------------------------------
|
|
typedef enum CmpRespErrEnum {
|
|
cmpRespErrNone = 0, // reserve 0 for no error
|
|
cmpRespErrSystem, // general Pilot system error
|
|
cmpRespErrUnknownCmd, // unknown command ID
|
|
cmpRespErrMemory, // insufficient memory
|
|
cmpRespErrParam, // invalid parameter
|
|
|
|
cmpRespErrLast // *KEEP THIS ENTRY LAST*
|
|
} CmpRespErrEnum;
|
|
|
|
|
|
//-------------------------------------------------------------------------
|
|
// Connection Management Extended Command ID's
|
|
//-------------------------------------------------------------------------
|
|
typedef enum CmpCmdEnum {
|
|
|
|
cmpCmdReserved = 0x0F, // range reserved for internal use
|
|
|
|
//----------------------------
|
|
// v2.0 COMMANDS
|
|
//----------------------------
|
|
cmpCmdXCommPrefs, // exchange communications protocol preferences
|
|
cmpCmdHShakeComplete, // hand-shake completion command
|
|
|
|
cmpCmdLast // *KEEP THIS ENTRY LAST*
|
|
} CmpCmdEnum;
|
|
|
|
|
|
|
|
//-------------------------------------------------------------------------
|
|
// v2.0 Connection Management Command/Response Structures
|
|
//-------------------------------------------------------------------------
|
|
|
|
// CmpCommPrefsType: common data structure shared by cmpCmdXCommPrefs and
|
|
// cmpCmdHShakeComplete. In cmpCmdXCommPrefs, the data structure is used
|
|
// to exchange capabilities. In cmpCmdHShakeComplete, the structure is
|
|
// used to instruct the Pilot on which settings/features to use. Some
|
|
// fields apply to direct PAD-based connections only and should be ignored
|
|
// by other transports such as TCP. More on this later(DOLATER...)
|
|
//
|
|
typedef struct CmpCommPrefsType {
|
|
// OFFSET
|
|
DWord maxPktDataSize;// 0; maximum supported packet data size
|
|
DWord maxDataBlkSize;// 4; maximum supported data block size
|
|
DWord maxBaudRate; // 8; maximum supported baud rate/baud rate to use
|
|
DWord hwHShakeAbove; // 12; requires hardware handshake above this baud rate
|
|
DWord flags; // 16; flags
|
|
DWord version; // 20; transport version (comm version)
|
|
DWord reserved2; // 24; RESERVED - SET TO NULL!
|
|
DWord reserved3; // 28; RESERVED - SET TO NULL!
|
|
// TOTAL: 32 bytes;
|
|
} CmpCommPrefsType;
|
|
|
|
|
|
//--------------------------------------
|
|
// Packet-level CRC preferences
|
|
//--------------------------------------
|
|
|
|
// cmpCommPrefsFlagSupportPktCRC16: if set, the transport layer is capable of
|
|
// CRC-16 protection of every data packet(v2.0 extension). (cmpCmdXCommPrefs)
|
|
#define cmpCommPrefsFlagSupportPktCRC16 0x80000000L
|
|
|
|
// cmpCommPrefsFlagUsePktCRC16: if set, instructs the transport layer to use
|
|
// the CRC-16 protection of every data packet(v2.0 extension). (cmpCmdHShakeComplete)
|
|
#define cmpCommPrefsFlagUsePktCRC16 0x00008000L
|
|
|
|
//--------------------------------------
|
|
// Data offset size preferences
|
|
//--------------------------------------
|
|
|
|
// NOTE:
|
|
// If specifying short offsets, short argument wrappers will be used.
|
|
// If specifying long offsets, long argument wrappers will be used.
|
|
|
|
// cmpCommPrefsFlagSupportShortOffsets: if set, indicates that the transport layer
|
|
// supports short(single-word) offsets/sizes in its data packets. The smaller
|
|
// field does not permit bigger blocks to be transmitted(v1.0-compatible). (cmpCmdXCommPrefs)
|
|
#define cmpCommPrefsFlagSupportShortOffsets 0x40000000L
|
|
|
|
// cmpCommPrefsFlagUseShortOffsets: if set, instructs the transport layer to use
|
|
// short(single-word) offsets/sizes in its data packets(v1.0-compatible). (cmpCmdHShakeComplete)
|
|
#define cmpCommPrefsFlagUseShortOffsets 0x00004000L
|
|
|
|
// cmpCommPrefsFlagSupportLongOffsets: if set, indicates that the transport layer
|
|
// supports long(double-word) offsets/sizes in its data packets. The larger
|
|
// field permits bigger blocks to be transmitted(v2.0 extension). (cmpCmdXCommPrefs)
|
|
#define cmpCommPrefsFlagSupportLongOffsets 0x20000000L
|
|
|
|
// cmpCommPrefsFlagUseLongOffsets: if set, instructs the transport layer to use
|
|
// long(double-word) offsets/sizes in its data packets(v2.0 extension). (cmpCmdHShakeComplete)
|
|
#define cmpCommPrefsFlagUseLongOffsets 0x00002000L
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////
|
|
// cmpCmdXCommPrefs
|
|
//////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// Description:
|
|
// Exchange communications preferences.
|
|
//
|
|
// Possible error codes
|
|
// cmpRespErrSystem,
|
|
// cmpRespErrMemory,
|
|
// cmpRespErrParam,
|
|
|
|
//---------------------
|
|
// Command arguments:
|
|
//---------------------
|
|
enum {
|
|
cmpXCommPrefsReqArgID = cmpFirstArgID
|
|
};
|
|
|
|
|
|
// cmpXCommPrefsReqArgID argument structure:
|
|
//
|
|
typedef struct CmpXCommPrefsReqType {
|
|
// OFFSET
|
|
CmpCommPrefsType prefs; // 0; CMP comm preferences
|
|
// TOTAL: 32 bytes;
|
|
} CmpXCommPrefsReqType;
|
|
|
|
|
|
//---------------------
|
|
// Response arguments:
|
|
//---------------------
|
|
enum {
|
|
cmpXCommPrefsPrefsRespArgID = cmpFirstArgID, // preferences argument
|
|
cmpXCommPrefsIPAddrRespArgID // preferred PC IP Address/host name
|
|
};
|
|
|
|
|
|
// cmpXCommPrefsPrefsRespArgID argument structure:
|
|
//
|
|
typedef struct CmpXCommPrefsPrefsRespType {
|
|
// OFFSET
|
|
CmpCommPrefsType prefs; // 0; CMP comm preferences
|
|
// TOTAL: 32 bytes;
|
|
} CmpXCommPrefsPrefsRespType;
|
|
|
|
|
|
// cmpXCommPrefsIPAddrRespArgID argument structure:
|
|
//
|
|
typedef struct CmpXCommPrefsIPAddrRespType {
|
|
// OFFSET
|
|
Byte ipAddr[1]; // 0; IP address/host name string, zero-terminated
|
|
// TOTAL: variable size;
|
|
} CmpXCommPrefsIPAddrRespType;
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////
|
|
// cmpCmdHShakeComplete
|
|
//////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// Description:
|
|
// Completes the Extended Connection Management hand-shake. Instructs
|
|
// the Pilot on which settings/features to use.
|
|
//
|
|
// Possible error codes
|
|
// cmpRespErrSystem,
|
|
// cmpRespErrMemory,
|
|
// cmpRespErrParam
|
|
|
|
//---------------------
|
|
// Command arguments:
|
|
//---------------------
|
|
enum {
|
|
cmpHShakeCompleteReqArgID = cmpFirstArgID
|
|
};
|
|
|
|
|
|
// cmpHShakeCompleteReqArgID argument structure:
|
|
//
|
|
typedef struct CmpHShakeCompleteReqType {
|
|
// OFFSET
|
|
CmpCommPrefsType final; // 0; final settings/features to use
|
|
// TOTAL: 32 bytes;
|
|
} CmpHShakeCompleteReqType;
|
|
|
|
|
|
//---------------------
|
|
// Response arguments:
|
|
//---------------------
|
|
|
|
// No response arguments; the response consists of the command header only
|
|
|
|
|
|
|
|
#endif // __CM_COMMON_H__
|