/******************************************************************* Copyright © 1995 - 1998, 3Com Corporation or its subsidiaries ("3Com"). All rights reserved. This software may be copied and used solely for developing products for the Palm Computing platform and for archival and backup purposes. Except for the foregoing, no part of this software may be reproduced or transmitted in any form or by any means or used to make any derivative work (such as translation, transformation or adaptation) without express written consent from 3Com. 3Com reserves the right to revise this software and to make changes in content from time to time without obligation on the part of 3Com to provide notification of such revision or changes. 3COM MAKES NO REPRESENTATIONS OR WARRANTIES THAT THE SOFTWARE IS FREE OF ERRORS OR THAT THE SOFTWARE IS SUITABLE FOR YOUR USE. THE SOFTWARE IS PROVIDED ON AN "AS IS" BASIS. 3COM MAKES NO WARRANTIES, TERMS OR CONDITIONS, EXPRESS OR IMPLIED, EITHER IN FACT OR BY OPERATION OF LAW, STATUTORY OR OTHERWISE, INCLUDING WARRANTIES, TERMS, OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND SATISFACTORY QUALITY. TO THE FULL EXTENT ALLOWED BY LAW, 3COM ALSO EXCLUDES FOR ITSELF AND ITS SUPPLIERS ANY LIABILITY, WHETHER BASED IN CONTRACT OR TORT (INCLUDING NEGLIGENCE), FOR DIRECT, INCIDENTAL, CONSEQUENTIAL, INDIRECT, SPECIAL, OR PUNITIVE DAMAGES OF ANY KIND, OR FOR LOSS OF REVENUE OR PROFITS, LOSS OF BUSINESS, LOSS OF INFORMATION OR DATA, OR OTHER FINANCIAL LOSS ARISING OUT OF OR IN CONNECTION WITH THIS SOFTWARE, EVEN IF 3COM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 3Com, HotSync, Palm Computing, and Graffiti are registered trademarks, and Palm III and Palm OS are trademarks of 3Com Corporation or its subsidiaries. IF THIS SOFTWARE IS PROVIDED ON A COMPACT DISK, THE OTHER SOFTWARE AND DOCUMENTATION ON THE COMPACT DISK ARE SUBJECT TO THE LICENSE AGREEMENT ACCOMPANYING THE COMPACT DISK. *------------------------------------------------------------------- * 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 #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__