The Zephyr Programmer’s Manual
`
`DRAFT
`
`Robert S. French
`John T. Kohl
`
`DRAFT
`
`Revision : 2.1
`—5 May 1989
`
`CSCO-1013
`Cisco v. Uniloc
`Page 1 of 88
`
`

`

`CONTENTS
`
`Contents
`
`1 Introduction
`
`2 Manual Conventions
`
`3 Overview of the Zephyr System
`
`3.1 Major Divisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4 General Concepts
`
`4.1 The Subscription Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`4.1.1 The class field . . . . . .
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`4.1.2 The instance field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`4.1.3 The recipient field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.1.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.1.5
`
`Subscription Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.1.6 Default Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.2 The User Location Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.2.1 Location Information . . . . . . . . . . . . . . . . . . . .
`
`. . . . . . . . . . . . . . . . .
`
`4.2.2 Exposure Levels
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`5 Programming Standard Applications
`
`5.1 The Zephyr Library and Include Files
`
`.
`
`. .
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`5.1.1 Naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`5.2 The ZNotice t Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`5.2.1 Components of the Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`. . .
`
`i
`
`1
`
`2
`
`3
`
`3
`
`5
`
`5
`
`5
`
`5
`
`5
`
`6
`
`6
`
`7
`
`7
`
`7
`
`7
`
`9
`
`9
`
`9
`
`9
`
`9
`
`5.2.2 Notice Kinds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
`
`5.2.3
`
`Field Structure of the Notice Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
`
`5.3 Acknowledgment Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
`
`5.4 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
`
`5.5
`
`Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
`
`5.5.1 ZInitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
`
`5.5.2 ZOpenPort
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
`
`5.6 Cleaning Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
`
`5.6.1 ZClosePort
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
`
`5.6.2 ZCancelSubscriptions
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
`
`CSCO-1013
`Cisco v. Uniloc
`Page 2 of 88
`
`

`

`CONTENTS
`
`ii
`
`5.7 Sending Notices . . . . . . . . . . .
`
`.
`
`5.7.1 ZSendNotice . . . . . . .
`
`. .
`
`5.7.2 ZSendList . . . . . . . . .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`5.7.3 Useful Information to Include in a Notice .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. . . . . .
`
`. . . . .
`
`. . . . 14
`
`. . .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . 15
`
`.
`
`.
`
`.
`
`. . .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. .
`
`. . . 15
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. . . .
`
`. .
`
`. . . 16
`
`. .
`
`. .
`
`. . .
`
`. . .
`
`. . . .
`
`. .
`
`. . 16
`
`5.7.3.1
`
`ZGetSender
`
`. .
`
`5.7.3.2
`
`ZGetRealm . .
`
`5.7.4
`
`Sending Binary Data . . .
`
`5.7.4.1
`
`ZMakeAscii
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`.
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`. .
`
`. . . . .
`
`. .
`
`. . 16
`
`.
`
`. .
`
`. .
`
`. .
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. . . .
`
`. . .
`
`. .
`
`. .
`
`. 16
`
`.
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. . .
`
`. . . . .
`
`. .
`
`. . 16
`
`. .
`
`. . .
`
`. .
`
`. . . 17
`
`Sending Authenticated Notices .
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`5.7.5
`
`5.7.6
`
`Sample Application . . . .
`
`5.8 Receiving Acknowledgments . . .
`
`5.8.1 Using Predicates . . . . .
`
`. .
`
`. .
`
`. .
`
`. .
`
`. .
`
`. .
`
`.
`
`. . .
`
`. . .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . 18
`
`5.8.1.1
`
`ZCompareUIDPred and ZCompareMultiUIDPred . .
`
`. . .
`
`. .
`
`. . .
`
`. . . . .
`
`. 19
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`. .
`
`. . .
`
`. .
`
`. .
`
`. .
`
`. . . . .
`
`. . . .
`
`. .
`
`. . 17
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. .
`
`. . . .
`
`. .
`
`. . .
`
`. 18
`
`5.8.2 ZCheckIfNotice . . . . . . .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`. . .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. .
`
`. . .
`
`. . 19
`
`5.8.3 ZFreeNotice
`
`. . . . . . . . .
`
`5.8.4 ZIfNotice . . . . . . . . . .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`. .
`
`5.8.5 ZCompareUID . . . . . . . .
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. . 19
`
`.
`
`. .
`
`.
`
`. . .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. . 19
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . 20
`
`. .
`
`. .
`
`. .
`
`. . . . .
`
`. . . .
`
`. .
`
`. . 20
`
`5.9 Subscribing to Notices
`
`. . . . . .
`
`. .
`
`5.9.1 ZSubscribeTo . . . . . . .
`
`.
`
`5.9.2 ZUnsubscribeTo . . . . . .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`.
`
`.
`
`. .
`
`. .
`
`5.8.6
`
`Sample Application . . . .
`
`.
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. . .
`
`. . .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . 21
`
`. .
`
`. . .
`
`. . .
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. .
`
`. 22
`
`.
`
`.
`
`. . .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. . .
`
`. . 22
`
`. . .
`
`. .
`
`. . . .
`
`. . .
`
`. .
`
`. . . 23
`
`5.9.3 ZCancelSubscriptions
`
`. . .
`
`. .
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`5.9.4
`
`Subscribing for the WindowGram Client
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. . 23
`
`5.9.4.1
`
`ZGetWGPort . .
`
`.
`
`.
`
`5.10 Receiving Notices . . . . . . . . .
`
`. .
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`. .
`
`. .
`
`. .
`
`. . . . .
`
`. .
`
`. . 23
`
`. . .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. .
`
`. . 23
`
`. .
`
`. .
`
`.
`
`. .
`
`. .
`
`. . .
`
`. . .
`
`. .
`
`.
`
`.
`
`. .
`
`. . . 24
`
`5.10.1 ZReceiveNotice . . . . . . .
`
`. .
`
`. .
`
`.
`
`5.10.2 Receiving Binary Data . .
`
`.
`
`.
`
`. .
`
`. .
`
`5.10.2.1 ZReadAscii
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`. .
`
`. .
`
`. .
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`. . .
`
`. .
`
`. . . . .
`
`. . .
`
`. .
`
`. . . 24
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. . .
`
`. .
`
`. . .
`
`. 24
`
`5.10.3 Receiving Authenticated Notices . .
`
`. .
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. . .
`
`. .
`
`. .
`
`. 24
`
`5.10.3.1 ZCheckAuthentication .
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`. . .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. . .
`
`. .
`
`. .
`
`. . .
`
`. . .
`
`. 24
`
`5.10.4 Sample Application . . . .
`
`5.11 Using the Input Queue . . . . . .
`
`.
`
`.
`
`5.11.1 ZPending . . . . . . . . . .
`
`5.11.2 ZQLength . . . . . . . . .
`
`.
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`.
`
`. .
`
`. .
`
`. .
`
`. . . . .
`
`. . .
`
`. . .
`
`. . 25
`
`.
`
`.
`
`.
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. . 26
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`. . .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. . 26
`
`. .
`
`. . .
`
`. . .
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. .
`
`. 26
`
`CSCO-1013
`Cisco v. Uniloc
`Page 3 of 88
`
`

`

`CONTENTS
`
`iii
`
`5.11.3 ZPeekNotice . . . . . . .
`
`. .
`
`.
`
`.
`
`.
`
`5.11.4 ZPeekIfNotice .
`
`. . . . . .
`
`. .
`
`. .
`
`.
`
`.
`
`5.12 Using Packets . . . . . . . . . . .
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`. . 27
`
`.
`
`. .
`
`. .
`
`.
`
`. . . . .
`
`. . . . .
`
`. . . . .
`
`. . 28
`
`. .
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. . .
`
`.
`
`. .
`
`. . .
`
`. .
`
`. 27
`
`. .
`
`. .
`
`. .
`
`.
`
`. . . .
`
`. . . . . . . . . .
`
`. . . . . 27
`
`5.12.1 ZFormatNotice . . . . . . .
`
`.
`
`.
`
`. .
`
`. .
`
`5.12.2 ZFormatNoticeList . . . .
`
`.
`
`. .
`
`. .
`
`5.12.3 ZSendPacket
`
`. . . . . . . .
`
`.
`
`.
`
`.
`
`.
`
`5.12.4 ZReceivePacket . . . . . . .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`.
`
`. . . .
`
`. . . . . . . . . .
`
`. . .
`
`. . 28
`
`. .
`
`. .
`
`.
`
`. .
`
`. .
`
`. . . . .
`
`. . . . .
`
`. . . .
`
`. . . . . 28
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`. . . .
`
`. . . . . . . . .
`
`. . .
`
`. . . 29
`
`5.12.5 ZPeekPacket
`
`. . . . . . . .
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`. .
`
`. . . .
`
`. . . . . . . . . . . . .
`
`. . 29
`
`. .
`
`. . . .
`
`. . . . . . . . . .
`
`. . . . . 30
`
`5.12.6 ZParseNotice . . . . . . . .
`
`5.12.7 Sample Application . . . . .
`
`5.13 Using Raw Notices . . . . . . . .
`
`5.13.1 ZFormatRawNotice . . . .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`. .
`
`. .
`
`. .
`
`.
`
`. .
`
`.
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. . . .
`
`. . . . . . . . . .
`
`. . .
`
`. . 30
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. . . .
`
`. .
`
`. .
`
`. . .
`
`. 32
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. . . .
`
`. . . . . . . . . .
`
`. . . . . 32
`
`.
`
`. . .
`
`. . . . .
`
`. . . . . . .
`
`. . . . . 32
`
`5.13.2 ZFormatSmallRawNotice
`
`. . .
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`5.13.3 ZFormatRawNoticeList
`
`. .
`
`. .
`
`. . .
`
`. .
`
`.
`
`5.13.4 ZFormatSmallRawNoticeList
`
`.
`
`. .
`
`. .
`
`. .
`
`5.13.5 ZSendRawNotice . . . . .
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. . . .
`
`. . . . . . . . . .
`
`. . . . . 32
`
`.
`
`. .
`
`. .
`
`.
`
`. . . . .
`
`. . . . . .
`
`. . . . .
`
`. 33
`
`. .
`
`. .
`
`. . .
`
`. . . . .
`
`. . . . . . .
`
`. . . . . 33
`
`5.13.6 ZSendRawList
`
`. . . . . . .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. . . . . . .
`
`. . . . .
`
`. . . . .
`
`. . 34
`
`. . .
`
`. .
`
`. . 34
`
`5.14 Retrieving User Locations
`
`. . . .
`
`5.14.1 ZLocateUser
`
`. . . . . . .
`
`.
`
`.
`
`5.14.2 ZNewLocateUser . . . . .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`. . . .
`
`. .
`
`. . . .
`
`. .
`
`. .
`
`.
`
`. . . .
`
`. . . . . .
`
`. . . .
`
`. . . . . 34
`
`. .
`
`. .
`
`. .
`
`.
`
`. .
`
`.
`
`. . . . .
`
`. . . . .
`
`. . . . .
`
`. . 34
`
`.
`
`.
`
`5.14.3 ZGetLocations . . . . . .
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. . . .
`
`. . . .
`
`. . . . . .
`
`. . . . . 35
`
`. . . . .
`
`. . . . . 35
`
`5.14.4 ZFlushLocations . . . . .
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`. . .
`
`5.14.5 Sample Application . . . . .
`
`5.15 Retrieving Subscriptions
`
`. . . . .
`
`.
`
`5.15.1 ZRetrieveSubscriptions . . .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. . .
`
`. . . . .
`
`. .
`
`. .
`
`. . . .
`
`. . . . . . . . . .
`
`. . .
`
`. . 35
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. . .
`
`. .
`
`.
`
`.
`
`. .
`
`. . .
`
`. . 36
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`. . . .
`
`. . . . . .
`
`. . . .
`
`. . . 36
`
`. . . . . 37
`
`5.15.2 ZRetrieveDefaultSubscriptions .
`
`5.15.3 ZGetSubscriptions . . . . . .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. . . . .
`
`. . . .
`
`. . . . .
`
`. .
`
`.
`
`. . . . . . . .
`
`. . . . .
`
`. . . . 37
`
`5.15.4 ZFlushSubscriptions . . .
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. . .
`
`. . . . .
`
`. . . . .
`
`. . . . .
`
`. . 37
`
`5.15.5 Sample Application . . . . .
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. . . .
`
`. . . . . . . . . .
`
`. . .
`
`. . 38
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`. . 39
`
`5.16 Variable Handling . . . . . . . . .
`
`5.16.1 ZGetVariable . . . . . . .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. . . . .
`
`. . . . . . . .
`
`. . . . .
`
`. . 39
`
`5.16.2 ZSetVariable . . . . . . . . .
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`. . . . .
`
`. . . . .
`
`. . . . .
`
`. . 39
`
`5.16.3 ZUnsetVariable . .
`
`. . . . .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`. . . .
`
`. . . . . . . . . .
`
`. . . . . 40
`
`5.16.4 Sample Application . . . . .
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`. .
`
`.
`
`.
`
`.
`
`. .
`
`. . . .
`
`. . . . . . . . . .
`
`. . .
`
`. . 40
`
`CSCO-1013
`Cisco v. Uniloc
`Page 4 of 88
`
`

`

`CONTENTS
`
`6 Advanced Programming Topics
`
`iv
`
`42
`
`6.1 Changing Your Location Information . . .
`
`. . .
`
`.
`
`. .
`
`.
`
`. . . . . . .
`
`. . . . . . . . . . .
`
`. . . . . 42
`
`6.1.1 ZSetLocation .
`
`.
`
`6.1.2 ZUnsetLocation .
`
`.
`
`.
`
`.
`
`.
`
`. . .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`.
`
`.
`
`. .
`
`. .
`
`.
`
`.
`
`. . .
`
`. . .
`
`. . .
`
`. . .
`
`.
`
`.
`
`. . . . . . . . . . . . . . . . . . . . 42
`
`. . . . . . .
`
`. . . . . . . . . . . . . 43
`
`6.1.3 ZFlushMyLocations
`
`.
`
`. . .
`
`.
`
`. .
`
`.
`
`. . .
`
`.
`
`. .
`
`.
`
`. .
`
`. . .
`
`. . . . . . . . . . . . . . . . . 43
`
`. . . 43
`
`6.2 Using Your Own Socket
`
`.
`
`.
`
`6.2.1 ZGetFD .
`
`. .
`
`.
`
`.
`
`. .
`
`6.2.2 ZSetFD .
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`. . .
`
`. . .
`
`.
`
`. . . .
`
`. . . . . . .
`
`. . . . . . . . . .
`
`.
`
`. . .
`
`.
`
`. .
`
`.
`
`. .
`
`.
`
`. . .
`
`. . . . . . . . . . . . . . . . . .
`
`. . 44
`
`. . .
`
`.
`
`. . .
`
`.
`
`. .
`
`.
`
`. .
`
`.
`
`. . .
`
`. .
`
`. . . . . . . .
`
`. . . . . . . . . 44
`
`. . . . . 44
`
`6.3 Changing the Destination Address .
`
`.
`
`. .
`
`.
`
`. . .
`
`. . .
`
`.
`
`. . . . . .
`
`. . . . . . . . . . .
`
`. . . .
`
`.
`
`. .
`
`.
`
`. .
`
`.
`
`.
`
`. .
`
`.
`
`. .
`
`. .
`
`. . . . . . . . . . . . . . . . . 44
`
`.
`
`.
`
`.
`
`. . .
`
`. . .
`
`.
`
`. . . . . . . . . . . . . . . . . . . 44
`
`. .
`
`.
`
`. . . . . . . .
`
`. . . . . . . . . . .
`
`. . . . 45
`
`. . .
`
`. . . . .
`
`. . . . . . .
`
`. . . . . . . . .
`
`. . 45
`
`6.3.1 ZGetDestAddr
`
`6.3.2 ZSetDestAddr
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`. . .
`
`. . .
`
`. . .
`
`6.4 Using Zephyr as a Rendezvous Service . .
`
`.
`
`. .
`
`6.5 Server Functions
`
`.
`
`.
`
`. .
`
`6.5.1 ZSetServerState .
`
`.
`
`.
`
`.
`
`.
`
`. . .
`
`. .
`
`. .
`
`. . .
`
`. .
`
`.
`
`.
`
`. . .
`
`. .
`
`6.5.2 ZSrvSendNotice .
`
`.
`
`. .
`
`.
`
`. . .
`
`. . .
`
`.
`
`.
`
`. .
`
`.
`
`. . .
`
`. . .
`
`.
`
`. .
`
`.
`
`. .
`
`. . .
`
`. . . . . . .
`
`. . . . . . . . . . 46
`
`.
`
`.
`
`. . .
`
`. . .
`
`.
`
`. . . . . . .
`
`. . . . . . . . . . . . . 45
`
`. .
`
`.
`
`. .
`
`.
`
`. . .
`
`. .
`
`. . . . . . . . .
`
`. . . . . . . 45
`
`6.5.3 ZSrvSendList .
`
`.
`
`.
`
`6.5.4 ZSrvSendRawList
`
`.
`
`.
`
`.
`
`. . . .
`
`.
`
`. .
`
`.
`
`. .
`
`.
`
`. . .
`
`. . . .
`
`. .
`
`. . . . . . . . .
`
`. . . . . . . 46
`
`6.5.5 ZFormatAuthenticNotice . .
`
`. .
`
`.
`
`. .
`
`.
`
`. . .
`
`.
`
`. .
`
`.
`
`. . . . . . .
`
`. . . . . . . . .
`
`. . . . 47
`
`6.6 Communicating with the WindowGram Client .
`
`. .
`
`6.6.1 Where to Send Notices .
`
`.
`
`. .
`
`.
`
`. . .
`
`.
`
`. .
`
`.
`
`.
`
`. . .
`
`. . . . . .
`
`. . . . . . . . . . .
`
`. . . . 47
`
`. .
`
`.
`
`. . . . . . . . . . . . . . . .
`
`. . .
`
`. . 47
`
`. .
`
`. . . . . . . .
`
`. . . . . . . . . 47
`
`6.6.2 Available Commands .
`
`.
`
`.
`
`. .
`
`.
`
`. .
`
`.
`
`. . .
`
`6.6.3
`
`Sample Application .
`
`.
`
`. . . . .
`
`.
`
`. .
`
`.
`
`. .
`
`.
`
`.
`
`. .
`
`.
`
`. .
`
`. . .
`
`.
`
`. . . . . .
`
`. . . . . . . . . . . .
`
`. . 48
`
`6.7 Communicating with the HostManager . .
`
`.
`
`. .
`
`.
`
`. .
`
`.
`
`. . . . . . . . .
`
`. . . . . . . . .
`
`. . . . . 48
`
`6.7.1 Where to Send Notices .
`
`.
`
`. .
`
`.
`
`. . .
`
`.
`
`. .
`
`.
`
`. .
`
`.
`
`. . . . . . . . . . . . . . . .
`
`. . .
`
`. . 49
`
`. .
`
`. .
`
`. . . . . . . .
`
`. . . . . . . . . 49
`
`6.7.2 Available Commands .
`
`.
`
`.
`
`. .
`
`.
`
`. .
`
`.
`
`. . .
`
`6.7.3
`
`Sample Application .
`
`.
`
`. . . . .
`
`.
`
`. .
`
`.
`
`. .
`
`.
`
`.
`
`. .
`
`.
`
`. . .
`
`.
`
`. . . . . .
`
`. . . . . . . . . . . .
`
`. . 49
`
`A Additional Examples
`
`51
`
`A.1 zwrite .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`. . .
`
`.
`
`. .
`
`.
`
`. . . .
`
`. . . . . . .
`
`. . . . . . . . .
`
`. . . . 51
`
`. . . . . . . 59
`
`A.2 zlocate .
`
`A.3 zstat
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. .
`
`. .
`
`.
`
`.
`
`. .
`
`.
`
`. . . .
`
`. .
`
`. . . . .
`
`. . . . . . . . . .
`
`. . .
`
`.
`
`. .
`
`.
`
`. . . . .
`
`. . . . . . . . . . .
`
`. . . . . . .
`
`. 61
`
`B Error Codes
`
`C Function Templates
`
`67
`
`69
`
`CSCO-1013
`Cisco v. Uniloc
`Page 5 of 88
`
`

`

`1 INTRODUCTION
`
`1.
`
`Introduction
`
`1
`
`Zephyr is a notice transport and delivery system developed at MIT Project Athena in 1987. It is an integrated
`system that provides the ability to send notifications, such as personal messages and system warnings, from one
`user or system service to another user or group of users.
`
`This manual describes the Zephyr library, the programmer’s interface to Zephyr. The Zephyr library consists
`of a collection of C language functions which allow the programmer to send and receive notices. Additional
`functions are provided in the library to modify how notices are distributed and to retrieve various pieces of infor-
`mation.
`
`Because this manual is primarily concerned with describing how to write an application which uses Zephyr,
`the internal workings of the Zephyr system are not discussed in detail. The interested reader can find additional
`information about Zephyr in the Zephyr design document [1].
`
`This manual is organized into four main sections as follows:
`
`Overview of the Zephyr System. This section describes the various components of Zephyr, and briefly de-
`scribes how they interact.
`
`General Concepts. This section describes the subscription and user location services.
`
`Programming Standard Applications. This section describes the Zephyr include files, the functions available
`in the Zephyr library, and many concepts that are relevant to programming Zephyr applications.
`
`Advanced Programming Topics. This section describes more advanced topics, including how to send control
`messages to Zephyr servers and HostManagers.
`
`In addition, the following appendices are provided:
`
`Additional Examples. Listings of zwrite, zlocate, and zstat, three standard Zephyr applications, are provided.
`
`Error Codes. All Zephyr error codes are listed with a brief description of each.
`
`Function Templates. Contains the templates for all of the functions mentioned in this manual.
`
`CSCO-1013
`Cisco v. Uniloc
`Page 6 of 88
`
`

`

`2 MANUAL CONVENTIONS
`
`2. Manual Conventions
`
`The following typographical conventions are used in this manual:
`
`2
`
`• A combination of class, class instance, and recipient (used for subscriptions) is written as <CLASS, IN-
`STANCE, RECIPIENT>.
`• A function template is written as follows:
`Function template for function:
`int function (arg1, arg2)
`int
`arg1;
`char
`*arg2;
`Prerequisite functions: Any functions that must be called before this one.
`Possible errors: All possible error codes that could be returned.
`• During the discussion of a function, arguments are written in bold type, like arg1.
`• Explicit members of a structure are also written in bold type, like member.
`• Filenames are written in slanted type, like filename.
`• Symbols that are defined in an include file are written in the normal type face, like ZERR NONE.
`• Strings that should be entered explicitly are written between quotes, like “rfrench”.
`
`CSCO-1013
`Cisco v. Uniloc
`Page 7 of 88
`
`

`

`3 OVERVIEW OF THE ZEPHYR SYSTEM
`
`3
`
`3. Overview of the Zephyr System
`
`3.1. Major Divisions
`
`The Zephyr system consists of three primary sections:
`
`• The Zephyr clients: These are the applications which actually use Zephyr to accomplish a task. Examples
`of clients are zwrite, which allows a user to send messages to other users, syslogd, which can send system
`warnings to users, and zwgc, the WindowGram client, which is the standard way for users to receive in-
`coming notices. Clients are generally written using the Zephyr library, which is the primary subject of this
`manual.
`• The HostManager: The HostManager is the intermediary between the clients and the rest of the Zephyr
`system. There is one HostManager running on every host which supports Zephyr programs. All clients send
`their outgoing notices to the HostManager. The HostManager then redistributes them to Zephyr servers for
`final delivery. The HostManager is in charge of determining if a particular server is still operational, and
`choosing a different server if necessary.
`• The Zephyr servers: These are the core of the Zephyr system. They are in charge of receiving notices from
`the clients (via the HostManagers), figuring out which clients or users should receive them, and distributing
`them. They are also in charge of keeping an up-to-date user location database. There can be any number of
`servers spread throughout a workstation environment. The servers keep in constant communication, sharing
`information about changed subscriptions and changed user locations.
`
`The communication between these three components is indicated schematically in Figure 1. One server and
`two hosts are shown. Each host consists of a HostManager and two clients. The sending host is sending a message
`which is received by a client on the receiving host. This is a simplified view of the computing environment. Nor-
`mally there would be hundreds or thousands of hosts, and several servers which keep in constant communication
`with each other.
`
`When a notice is sent from a client, many events happen “behind the scenes” that are not normally seen by
`the user. However, these events are very important to an applications programmer, and are listed in simplified
`form below. Note that many of these actions occur in parallel so this should not be construed as an absolute order
`of events.
`
`1. The source client program calls a Zephyr library routine which sends a notice.
`
`2. The Zephyr library sends the notice to the HostManager on the same host, and then waits for an acknowl-
`edgment.
`
`3. The HostManager receives the notice, and sends back an acknowledgment (HMACK) to the originating
`client.
`
`4. The Zephyr library receives the acknowledgment and returns to the calling program.
`
`5. The HostManager forwards the notice to a Zephyr server, and appends the notice to its queue of unacknowl-
`edged notices.
`
`6. The Zephyr server receives the notice, determines its recipients, and sends back an acknowledgment (SER-
`VACK) to the HostManager.
`
`7. The HostManager receives the acknowledgment, removes the notice from its queue of unacknowledged
`notices, and forwards a copy of the acknowledgment (SERVACK) to the client program.
`
`8. The client program receives and disposes of the acknowledgment.
`
`CSCO-1013
`Cisco v. Uniloc
`Page 8 of 88
`
`

`

`3 OVERVIEW OF THE ZEPHYR SYSTEM
`
`4
`
`Server
`
`6
`
`SERVACK
`
`C
`
`C
`
`notice
`
`CCO
`C
`
`C
`C
`
`C
`
`#"
`
`
`!HostManager
`
`notice
`
`6 n
`
`otice
`
`C
`C
`
`C
`
`C
`C
`
`#"
`
`C
`CCW
`
`
`!HostManager
`
`CLIENTACK
`
`Client
`
`
`
`Client
`
`HMACK
`&
`SERVACK
`
`?
`
`Client
`
`Client
`
`Receiving Host
`
`Sending Host
`
`Figure 1: Interaction between the various parts of a Zephyr system.
`
`9. The server forwards the notice to all recipients, and each time appends the notice to its queue of unacknowl-
`edged notices.
`
`10. A destination client receives the notice, and sends back an acknowledgment (CLIENTACK) to the server.
`
`11. The server receives the acknowledgment and removes the notice from its queue of unacknowledged notices.
`
`At each stage except the initial client to HostManager communication, if an acknowledgment is not received
`after a certain length of time, the notice is retransmitted. The initial client to HostManager communication is
`not retransmitted because there is little chance of a notice being lost when transmitted to a program on the same
`machine, and thus the lack of an acknowledgment indicates that something is very wrong.
`
`Flags may be set in the notice to indicate how much acknowledgment should be done. The possibilities range
`from no acknowledgments to the full acknowledgment scenario listed above. A discussion of the different levels
`of acknowledgment can be found in §5.2.2, and a discussion of the structure of acknowledgments can be found in
`§5.3.
`
`CSCO-1013
`Cisco v. Uniloc
`Page 9 of 88
`
`

`

`4 GENERAL CONCEPTS
`
`4. General Concepts
`
`5
`
`The following pages describe two concepts that may be useful to an applications programmer: The subscription
`paradigm for notice distribution and the user location system. The subscription paradigm is used to determine
`who will receive a given notice. The user location system is used to locate users.
`
`4.1. The Subscription Service
`
`Since the primary purpose of Zephyr is to deliver notices from one user or service to another, an important
`consideration is the means of specifying the recipient of a notice. An application must be able to send a given
`notice to a particular recipient, a known group of recipients, or an arbitrary, dynamically changing group of
`recipients. Zephyr accomplishes this by using a “subscription” service. Each Zephyr notice contains three fields
`which determine its recipients: zsub class, zsub instance, and zsub recipient (these used to lack the zsub prefix,
`but class is an illegal field name in C++). Users subscribe to specific triples of class, instance, and recipient, as
`described below, and these subscriptions are used to determine whether or not a given user will receive a notice.
`
`4.1.1. The class field
`
`The class is the top-level characteristic of a notice. It serves two primary purposes:
`
`• It is used as the first indicator of who might be able to receive the notice
`• It is used to determine if the sender is authorized to send a notice of the particular class (see §4.1.5, “Sub-
`scription Authorization”).
`
`For example, a “MESSAGE” class might be used to indicate a generic user-to-user message, and a “FILSRV”
`class might be used to indicate a file server message.
`
`4.1.2. The instance field
`
`The instance is a subdivision of the class. Its primary purpose is to narrow down the subject of the notice. For
`example, a notice with class “FILSRV” might contain the name of the fileserver as its instance. By itself, the
`instance is not very useful.
`It is simply an extra string like the class field that is used to determine possible
`recipients. However, the instance field allows wildcarding at subscription time. This means that a person could
`subscribe to file server messages from only a particular server by specifying the file server’s name as the instance,
`or all file server messages by specifying instance “*”.
`
`The only wildcard instance allowed is “*”. More complicated regular expressions (such as “*.MIT.EDU” to
`match all hosts in the MIT.EDU domain) are not allowed.
`
`4.1.3. The recipient field
`
`The recipient is the actual username of the person the notice is intended for. On systems which support the
`Kerberos authentication system [2], the recipient is the Kerberos principal of the recipient. A Kerberos principal
`is usually of the form username@realm, where realm is the name of the Kerberos realm controlling the user’s
`host.
`
`The recipient field may be wildcarded on both the sending and receiving ends. Once again “*” is the only
`valid wildcard. These limitations apply:
`
`CSCO-1013
`Cisco v. Uniloc
`Page 10 of 88
`
`

`

`4 GENERAL CONCEPTS
`
`6
`
`• If a user is subscribing to the triple <class, instance, username>, where username is the username of the
`user, only notices with the user’s explicit username in their recipient field will be sent to the user.
`• If a user is subscribing to the triple <class, instance, *>, only notices with a recipient of “*” will be sent
`to the user.
`
`Thus, if a user is subscribing to <MESSAGE, PERSONAL, rfrench@ATHENA.MIT.EDU>, and a message is
`sent to <MESSAGE, PERSONAL, *>, he will not receive it. Likewise, if a person is subscribing to <MESSAGE,
`PERSONAL, *>, and one is sent to <MESSAGE, PERSONAL, rfrench@ATHENA.MIT.EDU>, he will not receive
`it. Subscriptions can be combined. Thus if a person is subscribing to both of these triples, he will receive both
`messages. Note also that a person cannot subscribe to messages destined for users other than himself. These
`limitations combine to prevent a user from receiving another user’s personal messages.
`
`4.1.4. Examples
`
`A notice sent to <MESSAGE, PERSONAL, rfrench@ATHENA.MIT.EDU> will be received by user “rfrench” if he
`subscribes to:
`
`<MESSAGE, PERSONAL, rfrench@ATHENA.MIT.EDU>
`
`<MESSAGE, *, rfrench@ATHENA.MIT.EDU>
`
`But he would not receive it if he subscribed to:
`
`<FOOBAR, PERSONAL, rfrench@ATHENA.MIT.EDU>
`
`<MESSAGE, FOOBAR, rfrench@ATHENA.MIT.EDU>
`
`<MESSAGE, PERSONAL, *>
`
`Likewise, a notice sent to <FILSRV, PARIS.MIT.EDU, *> would be received by someone subscribing to:
`
`<FILSRV, PARIS.MIT.EDU, *>
`
`<FILSRV, *, *>
`
`But would not be received by someone subscribing to:
`
`<FILSRV, PARIS.MIT.EDU, user@ATHENA.MIT.EDU>
`
`<FILSRV, *, user@ATHENA.MIT.EDU>
`
`4.1.5. Subscription Authorization
`
`It is possible for a notice to be authenticated using the Kerberos authentication system [2]. The method used to
`do this is described in §5.7.5, “Sending Authenticated Notices.” When a notice is authenticated, a Zephyr server
`can perform a number of tests to determine if a user is allowed to send notices to or subscribe to messages from
`a particular class. The lists which determine these restrictions are kept on the server machines, and may not be
`updated by users. They are not available for inspection by users.
`
`Some of the restrictions that can be placed on a class are:
`
`CSCO-1013
`Cisco v. Uniloc
`Page 11 of 88
`
`

`

`4 GENERAL CONCEPTS
`
`7
`
`• Only specified users can send notices to this class
`• Only specified users can subscribe to notices from this class
`• Any notice sent to this class must be authenticated
`• Any notice sent to this class must have an instance equal to the sender of the notice
`
`A complete list of restrictions and how they are implemented is available in the Zephyr design document [1].
`
`4.1.6. Default Subscriptions
`
`The Zephyr servers maintain a list of default subscriptions which are normally added automatically to all sub-
`scriptions at the first subscription request for a given port (see §5.9 for details on when the default subscriptions
`are not added). These subscriptions are intended to make sure that the Operations staff can easily notify all users.
`
`4.2. The User Location Service
`
`In addition to storing subscription information about each user, the Zephyr servers maintain a database of the
`location of each currently logged-in user. This information is not used by the servers to determine where to send
`notices—a client can subscribe to notices without being registered in the location database—but is made available
`to other users for personal use.
`
`Normally a user is registered by a standard client application (such as the WindowGram client) upon login,
`and is deregistered at logout. However, an application may occasionally desire to modify or remove user location
`information from the database. The ZSetLocation function (§6.1.1) will do this.
`
`4.2.1. Location Information
`
`The following information is stored by the Zephyr servers for each registered user:
`
`• The name of the host the user is registered from.
`• The name of the terminal the user is using; on a workstation that supports the X window system, this may
`be the display name instead.
`• The date and time the user was registered.
`
`4.2.2. Exposure Levels
`
`A user can register at any of a number of exposure levels. An exposure level tells the servers who will be able to
`access information about the user’s location, and whether or not the registration will be announced to other users.
`When a registration can be announced to other users, the Zephyr server sends it to users subscribing to <LOGIN,
`user, *>, where user is a fully qualified Kerberos principal (user@realm). If Kerberos is not in use, the user field
`will be user@host.
`
`The following exposure levels are defined:
`
`• None: The user’s location information is completely hidden, and the registration is not announced.
`• Opstaff: Only members of the site’s operational staff can retrieve the user’s location information, and the
`registration is not announced.
`
`CSCO-1013
`Cisco v. Uniloc
`Page 12 of 88
`
`

`

`4 GENERAL CONCEPTS
`
`8
`
`• Realm-Visible: Only users authenticated in the local Kerberos realm can retrieve the user’s location infor-
`mation, and the registration is not announced.
`• Realm-Announced: Only users authenticated in the local Kerberos realm can retrieve the user’s location
`information, and the registration is announced to all interested users in the local realm.
`• Net-Visible: All users can retrieve the user’s location information. The registration is announced to all
`interested users in the local realm.
`• Net-Announced: All users can retrieve the user’s location information, and the registration is announced
`to all interested users.
`
`When Kerberos is not enabled, each host is interpreted as a separate realm for purposes of exposure levels and
`login notices.
`
`CSCO-1013
`Cisco v. Uniloc
`Page 13 of 88
`
`

`

`5 PROGRAMMING STANDARD APPLICATIONS
`
`9
`
`5. Programming Standard Applications
`
`The following sections describe the concepts involved in using the Zephyr library, and the function calls that
`would be used in a standard Zephyr application.
`
`5.1. The Zephyr Library and Include Files
`
`Applications that want to use the features of Zephyr must link against the Zephyr library and the com err library,
`and possibly the Kerberos library and DES library. The Zephyr library contains the functions defined in the
`later sections of this document. It is usually called libzephyr.a, and may be included in an application by
`specifying -lzephyr on the compile or link line.
`
`The com err library contains error-reporting functions (See the com err design document [3].). It is usually
`called libcom err.a, and may be included in an application by specifying -lcom err on the compile or
`link line.
`
`The Kerberos library contains Kerberos functions. It is usually called libkrb.a, and may be included in
`an application by specifying -lkrb on the compile or link line.
`
`The DES library contains DES functions. It is usually called libdes.a, and may be included in an appli-
`cation by specifying -ldes on the compile or link line.
`
`The main Zephyr include file, zephyr.h, must also be included in all source files that use Zephyr func-
`tions.
`It contains many Zephyr-relate