idnits 2.17.1 draft-day-sgap-01.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 3) being 854 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 3 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 173: '...the size of values. A server MUST NOT...' RFC 2119 keyword, line 183: '...owever, a client MAY decline one of th...' RFC 2119 keyword, line 184: '...ame. The server MAY refuse to allow a...' RFC 2119 keyword, line 185: '...r names. The server MAY also limit the...' RFC 2119 keyword, line 187: '...server MAY require that a given princi...' (22 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'RFC-1034' on line 892 looks like a reference -- Missing reference section? 'NSTP' on line 888 looks like a reference -- Missing reference section? 'DPM' on line 884 looks like a reference Summary: 11 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Mark Day 2 Expires: September 13, 1998 Lotus Development Corporation 4 Simple General Awareness Protocol (SGAP) 5 Revision 1 7 draft-day-sgap-01.txt 9 1. Status of this Memo 11 This document is an Internet-Draft. Internet-Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its 13 areas, and its working groups. Note that other groups may also 14 distribute working documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six 17 months and may be updated, replaced, or obsoleted by other 18 documents at any time. It is inappropriate to use Internet- 19 Drafts as reference material or to cite them other than as 20 "work in progress." 22 To view the entire list of current Internet-Drafts, please check 23 the "1id-abstracts.txt" listing contained in the Internet-Drafts 24 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 25 (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East 26 Coast), or ftp.isi.edu (US West Coast). 28 2. Abstract 30 The Simple General Awareness Protocol (SGAP) provides notifications of 31 changes to small data items. The changes are selectively made 32 available to a large collection of viewers. This facility is most 33 useful for a class of applications variously called people locators, 34 colleague-awareness tools, people browsers, or "buddy lists". 36 3. Contents 38 1. Status of this Memo 39 2. Abstract 40 3. Contents 41 4. Introduction 42 5. Protocol Model 43 5.1 Items 44 5.2 Viewers 45 5.3 Viewer and Item Sharing Name 46 5.4 Authentication 47 5.5 Properties 48 5.6 Declarations 49 5.7 Notifications 50 5.8 Default Viewer 51 5.9 Multiple Items and Viewers 52 5.10 Contexts 53 6. Server-Server Protocol Not a Special Case 54 7. Special Server Behavior 55 8. Protocol Specification 56 8.1 Model 57 8.2 Summary of Messages 58 8.3 Header Structure 59 8.4 Body Encoding 60 8.4.1 Types 61 8.5 Messages 62 8.5.1 Init 63 8.5.2 Declare 64 8.5.3 Create 65 8.5.4 Modify 66 8.5.5 Delete 67 8.5.6 Split Viewers 68 8.5.7 Merge Viewers 69 8.5.8 List Viewers 70 8.5.9 Viewer List 71 8.5.10 Fetch 72 8.5.11 Fetch Response 73 8.5.12 Enable 74 8.5.13 Disable 75 8.5.14 Creation 76 8.5.15 Modification 77 8.5.16 Deletion 78 8.5.17 OK 79 8.5.18 Error 80 9. Acknowledgements 81 10. References 82 11. Changes made in Revision 1 83 12. Author's Address 85 4. Introduction 87 Synchronous collaboration in a network environment is determined by 88 the characteristics of people and how they work together. We have 89 found it useful to divide synchronous collaboration into three phases: 90 awareness, conversation, and sharing. A collaboration proceeds 91 through the phases in that order. Multiple overlapping and returning 92 sequences through this model are possible 94 i. Awareness: A user first becomes aware that other users, groups, or 95 resources of interest are available. Awareness is comparable to the 96 function of peripheral vision. 98 ii. Conversation: Having become aware of those others, the user starts 99 one or more conversations or conferences with those people (via 100 various media, such as voice, text, or video). 102 iii. Sharing: Being engaged in conversations, the user finds it useful 103 to share documents or other objects. Such sharing adds value in two 104 ways. First, it allows for richer collaboration than is possible with 105 conversation alone, such as jointly editing a document or playing a 106 real-time game. Second, it allows for conversational ellipsis: for 107 example, a gesture at a sentence accompanied by the phrase "I don't 108 that starts with 'Synchronous.'" 110 The Simple General Awareness Protocol (SGAP) is intended to be used 111 primarily for awareness, the first phase of the process. SGAP is not 112 intended as a mechanism for conversation or sharing; there are a 113 number of technologies that can be used for various forms of 114 conversation and sharing, and relatively few that allow for the 115 features required of an awareness system. 117 In addition, the requirements in the two contexts are fundamentally 118 different. An awareness system involves the selective exposure of 119 small amounts of information to large numbers of others, with 120 relatively loose consraints on latency. A conversation and sharing 121 system involves the sharing of large amounts of information 122 (high-bandwidth channels) among a relatively small group, with 123 relatively tight constraints on latency. To use a telephone-system 124 analogy, we consider awareness to be largely "signalling" for the 125 higher-bandwidth "connection" represented by the conversations and 126 sharing. 128 5. Protocol Model 130 Conceptually, a server implements a matrix, with a row for each 131 distinct item to be shared and a column for each distinct viewer with 132 whom that information should be shared. The intersection of a column 133 and row is called a cell, and corresponds to the view of an item 134 delivered to a viewer. 136 5.1 Items 138 Each item has a distinct item name. The item name is used simply as an 139 identifier for the item; in general, there are no additional semantics 140 (however, a small number of item names are significant to the 141 server). For example, "www.lotus.com" is different from 142 "http://www.lotus.com", though both are legal item names, as is any 143 UTF-8 encoded string of non-zero length (such as "Bill Clinton" or 144 "X%66 52 *$#"). 146 5.2 Viewers 148 Each viewer also has a distinct viewer name. Again, the viewer name is 149 used simply as an identifier for the viewer; in general, there are no 150 additional semantics (again, a small number of viewer names are 151 significant to the server). 153 5.3 Viewer and Item Sharing Name 155 Although distinct items have distinct names, and distinct viewers have 156 distinct names, it is acceptable for an item and a viewer to have the 157 same name. Indeed, such name-sharing is the typical case. 159 5.4 Authentication 161 The protocol assumes an authenticated connection between client and 162 server. The authenticated client entity is referred to as the 163 principal. 165 5.5 Properties 167 A property is the smallest unit created, destroyed, or modified by 168 the protocol. A property consists of a name, a type, and a value. 169 Both the name and type of a property are UTF-8 encoded text strings, 170 with relatively few restrictions on the form of the strings. A 171 property's value is zero or more bytes of arbitrary 172 data. Architecturally, a value may be up to 4 gigabytes, but servers 173 may set a smaller bound on the size of values. A server MUST NOT 174 break the connection only because a client sends an excessively-large 175 value. Instead, the server must send an error message, then count 176 bytes past the offending element and continue with the next usable 177 request. 179 5.6 Declarations 181 A client declares its use of a given name. Usually, such a declaration 182 means that the client both acts as the item with that name, and acts 183 as the viewer with that name; however, a client MAY decline one of the 184 roles when it declares a name. The server MAY refuse to allow a given 185 principal to declare particular names. The server MAY also limit the 186 number of names that a given principal may declare. Finally, the 187 server MAY require that a given principal use one of a restricted set 188 of names. 190 A client declared as a given item can affect (change the properties 191 of) the row corresponding to that item. A client can only affect a row 192 if it has declared itself as that item. A client declared as a given 193 viewer can see (get the values of) the column corresponding to that 194 viewer. A client can only see a column if it has declared itself as 195 that viewer. 197 5.7 Notifications 199 A client may enable or disable notifications on any item that it can 200 see. When notifications are enabled on an item, any change in the 201 properties of that item cause a notification message to be sent to 202 that client. 204 5.8 Default Viewer 206 There is a special viewer column representing the default viewer. This 207 column does not have an associated viewer name, and accordingly can 208 never be directly accessed by a viewer. However, a client declared as 209 an item can determine which properties are in the default column for 210 that item, as well as determining which viewer names actually map to 211 the default column for that item. 213 The default-viewer column allows the possibility of both 214 default-accessible and default-inaccessible sharing of 215 information. For a default-accessible item, the item's value appears 216 in the default column's cell. Viewers to be excluded are named 217 explicitly, with no value (or substitute values) appearing in the 218 cells of those columns. For a default-inaccessible item, no value 219 appears in the default column's cell. Viewers who can access the item 220 are named explicitly, with the appropriate value appearing in the 221 cells. 223 5.9 Multiple Items and Viewers 225 A single client-to-server transport connection can carry out commands 226 on behalf of an arbitrary number of items and viewers. In the case of 227 a "buddy list," the expected behavior is to act on behalf of a single 228 item and a single viewer, both representing the person using the 229 client. 231 5.10 Contexts 233 A single physical server can implement a number of logical servers, 234 each with its own matrix unrelated to the others but (usually) using 235 the same rules for control of names. Each such logical server is 236 distinguished by a different value of the context field. Contexts are 237 named by UTF-8 encoded strings. The server's default context is named 238 by the zero-length string. The server MAY refuse to allow a given 239 principal to use particular context names. The server MAY also limit 240 the number of names that a given principal may declare. Finally, the 241 server MAY require that a given principal use one of a restricted set 242 of names. 244 6. Server-Server Protocol Not a Special Case 246 Multiple servers can coordinate their state using the existing 247 protocol. The protocol allows both a "publish" model and a "subscribe" 248 model, favoring neither over the other. 250 Consider a server P that has some items (x,y,z) being updated by 251 clients. To "publish" those items and make them available to Q's 252 clients, P connects to another server Q and declares the names 253 (x,y,z). From Q's perspective, P is just another client (although P's 254 authentication to Q likely establishes that P's principal has more 255 privileges than the typical client). 257 Correspondingly, to "subscribe" to those items, a third server R can 258 connect to P and declare the names (x,y,z), choosing to be only in the 259 viewer role on those names. 261 Although SGAP supports the publication or subscription of items across 262 multiple servers, the protocol does not specify how clients or servers 263 arrange for such publication or subscription to take place. Note that 264 there is no mechanism in the protocol that would either prevent or 265 detect a request loop among servers. 267 7. Special Server Behavior 269 Some properties provide information to the server about how to treat 270 an item. For example, some items should be deleted if the reponsible 271 client is disconnected, while others should persist; this difference 272 in behavior is encoded in one or more special properties understood by 273 the server. 275 The properties understood by a server are collectively called the 276 server schema. Server schemas are defined independently of the 277 protocol. However, the mechanism to determine the schema of a server 278 is fixed by the protocol. 280 The server schema of a given server is exposed as the item 281 named "SGAP:Schema-Root". Within that item, the properties named 282 "SchemaName" and "SchemaVersionNumber" are guaranteed to be 283 defined. The value of SchemaName is a UTF-8 encoded text string. The 284 value of SchemaVersionNumber is a 4-byte array, representing an 285 unsigned integer in network order. 287 8. Protocol Specification 289 8.1 Model 291 We consider an awareness service to be a map: 293 context X viewer name X item name -> property* 295 That is, for each triplet of , there is 296 a collection of zero or more properties. 298 8.2 Summary of Messages 300 In general, messages are carried via a reliable bytestream transport, 301 such as TCP. The following table summarizes the protocol messages and 302 their function. 304 Message Meaning 306 Init Start interaction with server 307 Declare Claim right to act on behalf of viewers 308 and/or items 309 Create Create new properties of an item exposed 310 to a viewer 311 Modify Modify the properties of an item exposed to 312 a viewer 313 Delete Delete the properties of an item exposed to 314 a viewer 315 Split Viewers Inform server that these viewers should see a 316 private (non-default) view of the item 317 Merge Viewers Inform server that these viewers should see 318 the default view of the item 319 List Viewers Get the names of viewers with private views 320 of an item 321 Viewer List Reply containing the names of viewers with 322 private views of an item 323 Fetch Get the properties provided to a viewer for 324 a set of items 325 Fetch Reponse Reply containing the properties for a set 326 of items 327 Enable Allow delivery of change notifications 328 Disable Suppress delivery of change notifications 329 Creation Notify of property creation 330 Modification Notify of property modification 331 Deletion Notify of property deletion 332 OK Acknowledge successful completion 333 Error Explain an error condition 335 8.3 Header Structure 337 The header of each message consists of a one-byte version number, a 338 one-byte opcode, one reserved byte, one default-flag byte, and a 339 4-byte length (in network order) of the following body in bytes, not 340 including the header or length itself. 342 +--------------+--------------+--------------+--------------+ 343 | 0x85 | opcode | 0x00 | default-flag | 344 +--------------+--------------+--------------+--------------+ 345 | length in bytes of following body | 346 +-----------------------------------------------------------+ 347 | body | 348 + . + 349 | . | 350 + . + 352 The version number MUST be set to 0x85 in this version of the protocol. 354 The opcode identifies the operation to be carried out in response to 355 the message. 357 The reserved byte MUST be set to 0x00 in this version of the protocol 358 and MUST be ignored by implementations. 360 The default-flag byte is used to indicate whether an operation applies 361 to the default cell(s) and/or all other cell(s). The flag is needed 362 because the default cells have no name: they correspond to every 363 viewer for which the server does not have a viewer-specific cell. In 364 addition, without using such a mechanism, there is no way to name "all 365 viewers other than default." 367 The following table lists the acceptable values for the default-flag 368 byte and their interpretation. 370 0x00 All viewer cells to which the operation applies are explicitly 371 named in the body. 372 0x01 The default viewer cell(s) are affected in addition to any 373 cells explicitly named in the body. 374 0x02 All cells except the default viewer cell(s) are affected. 375 0x03 All cells of the item(s) are affected. 377 No other values are legal. That is, the two low-order bits serve as 378 flags, and the other bits MUST be zero. 380 The default-flag byte is only used for a few message types, but there 381 would be no advantage to putting its flags into the body of those 382 messages. Neither the version number nor the opcode requires more 383 than a single byte, while it is advantageous for some machines to have 384 the 4-byte length aligned on a 4-byte boundary. So the default-flag 385 byte uses a byte that would otherwise be "wasted" in the header. 387 8.4 Body Encoding 389 A "vector" is encoded as a 4-byte unsigned integer in network order, 390 followed by the number of elements determined by that integer's value, 391 followed by 0 to 3 padding bytes. The number of padding bytes is 392 chosen so that the entire vector's length in bytes is a multiple of 393 4. Padding bytes are chosen to alternate between the values 0xAC and 394 0xDC. Implementations MUST ignore the value of padding bytes 395 received. 397 A "String" is a vector of bytes. The bytes contain the UTF8 encoding 398 of character data. There is no null character terminating the string. 400 A "Property" is two Strings (name and type) followed by a vector of 401 bytes. In contrast to the Strings, the value vector may contain 402 arbitrary bytes, including values that are not allowed in a UTF-8 403 encoding. A Property is considered to be a single element. Thus, a 404 vector of Properties starts with a count of the number of Properties, 405 not the (three times larger) number of component vectors. 407 8.4.1 Types 409 The following type names and meanings are defined by the 410 protocol. 412 Type Name bytes in value Interpretation 414 SGAP:boolean 1 0x00 = false 415 0x01 = true 416 other values illegal 417 SGAP:ternary 1 0x00 = no 418 0x01 = yes 419 0x02 = maybe 420 SGAP:byte 1 arbitrary byte value 421 SGAP:int 4 32-bit 2's complement 422 integer in network order 423 SGAP:unsigned 4 32-bit unsigned integer 424 in network order 425 SGAP:string arbitrary UTF-8 encoded 426 SGAP:javastring 2+arbitrary UTF-8 encoded with 16-bit 427 prefix count 428 SGAP:cstring arbitrary ASCII with null terminator 429 SGAP:xml-1.0 arbitrary expression, XML 1.0 syntax 430 SGAP:MIME arbitrary MIME-encoded value 432 Other type names MAY be defined. Such type names SHOULD take the form 433 of an internet domain name [RFC-1034] identifying the naming entity, 434 followed by a colon ":", then the type name assigned by the naming 435 entity. Thus "lotus.com:DominoInteger", "ietf.org:IANARegistryEntry", 436 and "cl.cam.ac.uk:2@3" are all acceptable type names. 438 8.5 Messages 440 For each message, we present information in the following form (using 441 the Split Viewers message as an example): 443 8.5.5 Split Viewers 445 Opcode: 0x05 447 ContextName: String 448 ItemName: String 449 ViewerNames: vector of String 451 Indicates to the server that the named viewers are not to be 452 given the default viewer cell for the named item in the named 453 context. The default-flag byte must be cleared (value of 454 0x00). 456 The numbered section heading gives the name of the message (Split 457 Viewers, in this case). 459 The next line gives the value for the opcode byte, in 460 hexadecimal. Accordingly, a message with the opcode 5 is a Split 461 Viewers message. 463 The next lines give the encoding of the message's body. The body of a 464 Split Viewers consists of three elements in an implicit sequence: a 465 String, another String, and a vector of Strings. The names of the 466 elements serve as a clue to their function, and provide a way for the 467 explanatory text to refer to these elements. The names of elements 468 (such as "ContextName") are for explanation only and are not 469 explicitly represented in protocol messages. 471 The final paragraph summarizes the function of the message and the 472 meaning of its elements, including any constraints on the values in 473 the body or in the header. 475 8.5.1 Init 477 Opcode: 0x01 479 This message MUST be sent to the server before any other SGAP messages 480 are sent. It provides the server an opportunity to initialize state 481 related to the authentication of the transport connection and its 482 effect on the server's behavior for this client. 484 8.5.2 Declare 486 Opcode: 0x02 488 ContextName: String 489 Name: String 490 MultiNames: vector of NameDeclaration 492 where NameDeclaration is 494 DeclaredName: String 495 NameModifiers: vector of integer 497 Declares to the server that the client will use Name as its name. The 498 client can affect the item with that name and act as the viewer with 499 that name. 501 Name and MultiNames are mutually exclusive: if Name is a 502 non-zero-length String, MultiNames MUST be a zero-length vector. If 503 Name is a zero-length String, MultiNames MUST NOT be a zero-length 504 vector. 506 For each NameDeclaration in MultiNames, the DeclaredName MUST NOT be a 507 zero-length String. Implementations MUST reject requests in which the 508 same DeclaredName appears more than once. 510 Elements of NameModifiers can be any of the following: 512 0x1 "ItemOnly" the client may affect the named item but will not 513 act as the named viewer. 514 0x2 "ViewerOnly" the client may act as the named viewer but will 515 not affect the named item. 516 0x3 "Exclusive" the client insists that it is the only declarer 517 of this name in this form. 518 0x4 "ItemViewer" the client may affect the named item and may act 519 as the named viewer. 521 An implementation MUST reject any request that includes more than one of 522 "ItemOnly", "ViewerOnly", or "ItemViewer" in NameModifiers. 524 "Exclusive" alone or with "ItemViewer" means that no other client may 525 affect the item by that name or act as the viewer by that name. The 526 item is still potentially available to other viewers. 528 "Exclusive" and "ItemOnly" together mean that no other client may 529 affect the item by that name, although other clients may declare the 530 same name "ViewerOnly". 532 "Exclusive" and "ViewerOnly" together mean that no other client may 533 act as the viewer with that name, although other clients may declare 534 the same name "ItemOnly". 536 8.5.3 Create 538 Opcode: 0x03 540 ContextName: String 541 ItemName: String 542 ViewerNames: vector of String 543 NewProperties: vector of name-value pairs 545 Creates new properties contained within the named item in the named 546 context. Affects the cells determined by the combination of the 547 default-flag byte and ViewerNames. 549 A single create request takes place atomically. No client sees the 550 result of a partially executed create. 552 An implementation MUST reject the creation of a property that already 553 exists in any of the cells affected. 555 Causes Creation notifications (see 8.5.14) to be delivered to viewers 556 that have enabled notifications. 558 8.5.4 Modify 560 Opcode: 0x04 562 ContextName: String 563 ItemName: String 564 ViewerNames: vector of String 565 NewProperties: vector of name-value pairs 567 Replaces the properties contained within the named item in the named 568 context. Affects the cells determined by the combination of the 569 default-flag byte and ViewerNames. 571 A single modify request takes place atomically. No client sees the 572 result of a partially executed modify. 574 An implementation MUST reject the modification of a property that does 575 not exist in any of the cells affected. 577 Causes Modification notifications (see 8.5.15) to be delivered to 578 viewers that have enabled notifications. 580 8.5.5 Delete 582 Opcode: 0x05 584 ContextName: String 585 ItemName: String 586 ViewerNames: vector of String 587 NewProperties: vector of name-value pairs 589 Deletes the properties contained within the named item in the named 590 context. Affects the cells determined by the combination of the 591 default-flag byte and ViewerNames. 593 A single delete request takes place atomically. No client sees the 594 result of a partially executed delete. 596 An implementation MUST reject the deletion of a property that does not 597 exist in any of the cells affected. 599 Causes Deletion notifications (8.5.16) to be delivered to viewers that 600 have enabled notifications. 602 8.5.6 Split Viewers 604 Opcode: 0x06 606 ContextName: String 607 ItemName: String 608 Copy: Byte 609 ViewerNames: vector of String 611 Indicates to the server that the named viewers are not to be given the 612 default viewer cell for the named item in the named context. 614 If Copy has the value 0x01, then the current properties of the default 615 viewer cell are copied into the new cells so that no change in state 616 is visible to the named viewers; no notifications are sent to any 617 clients that have notifications enabled. Otherwise, the new cells 618 contain no properties, and the affected viewers receive Destroyed 619 notifications for all of the properties that they could see before. 621 The default-flag byte must be cleared (value of 0x00). 623 8.5.7 Merge Viewers 625 Opcode: 0x07 627 ContextName: String 628 ItemName: String 629 ViewerNames: vector of String 631 Indicates to the server that the named viewers are to be given the 632 default viewer cell for the named item in the named context. The 633 default-flag byte must be cleared (value of 0x00). 635 For affected clients that have enabled notifications, the following 636 rules are used to determine notifications: 638 i. For any property that is no longer present in the default cell, the 639 clients receive a Destroyed notification. 641 ii. For any property present in the default cell that was not present 642 in the original cell, the clients receive a Created notification. 644 iii. For any property present in both original and default cell, the 645 client receives a Changed notification if and only if the type and/or 646 value of the property differs. 648 8.5.8 List Viewers 650 Opcode: 0x08 652 ContextName: String 653 ItemName: String 655 Requests a list of the names of named viewers (those viewers with 656 other than the default view of the named item). The default-flag byte 657 must be cleared (value of 0x00). 659 The server MUST reject this request if sent by any client that has not 660 succesfully declared itself as the named item. 662 8.5.9 Viewer List 664 Opcode: 0x09 666 ContextName: String 667 ItemName: String 668 Viewers: vector of String 670 The Viewer list is the list of explicitly named viewers for the object 671 named. All other viewers receive the default properties for that 672 object. Note that the server does not know or care whether there are 673 any actual differences between the properties in the default view cell 674 and the properties in other view cells. The default-flag byte must be 675 cleared (value of 0x00). 677 8.5.10 Fetch 679 Opcode: 0x0A 681 ContextName: String 682 ViewerName: String 683 ItemNames: vector of String 684 AndEnable: vector of bytes 686 Requests the properties of the named items, on behalf of the named 687 viewer. The default-flag byte must be cleared (value of 0x00). Each 688 name in ItemNames MUST be distinct. 690 A single fetch request takes place atomically. No client sees the 691 result of a partially executed fetch. 693 If AndEnable is not a zero-length vector, then it MUST have the same 694 number of elements as ItemNames. Each byte MUST be either the value 695 0x00 (ignore) or 0x01 (enable). For each byte that has the value 696 "enable", the request enables change notifications immediately for the 697 item named in the corresponding position of ItemNames (see "Enable", 698 below). 700 8.5.11 Fetch Response 702 Opcode: 0x0B 704 ContextName: String 705 ViewerName: String 706 ObjectInfo: vector of ItemState 708 where ItemState is 710 ItemName: String 711 ItemProperties: vector of name-value pairs 713 Provides the properties of the named items, in response to a Fetch 714 request. The default-flag byte must be cleared (value of 0x00). 716 8.5.12 Enable 718 Opcode: 0x0C 720 ContextName: String 721 ViewerName: String 722 ItemName: vector of String 724 Enables the delivery of change notifications. After this command is 725 received, the server will deliver notifications to the named viewer 726 whenever any of the named items in the named context change in a way 727 that is visible to the viewer. The default-flag byte must be cleared 728 (value of 0x00). 730 Depending on special server behavior (see Section 7) the server may 731 deliver these notifications by a different channel rather than an 732 existing SGAP transport connection. For example, the server may use a 733 connectionless protocol such as UDP, or may open a server-to-client 734 TCP connection to deliver the notification. 736 8.5.13 Disable 738 Opcode: 0x0D 740 ContextName: String 741 ViewerName: String 742 ItemNames: vector of String 744 Disables the delivery of notifications of changes. After this command 745 is received, the server will not deliver any notifications to the 746 named viewer from changes to the named items. The default-flag byte 747 must be cleared (value of 0x00). 749 After issuing a disable request, a client must be prepared to receive 750 some number of spurious (late) notifications and silently discard them. 752 8.5.14 Creation 754 Opcode: 0x0E 756 ContextName: String 757 ViewerNames: vector of String 758 ItemName: String 759 ItemProperties: vector of name-value pairs 761 Provides a notification to the named viewers that the named properties 762 have been created as part of the named item (using a Create command). 764 The default-flag byte must be cleared (value of 0x00). 766 The ViewerNames are the viewers declared by this client that are 767 receiving this notification, not all viewers receiving the 768 notification. In particular, note that ViewerNames in this message is 769 not identical to ViewerNames in the Create request that gives rise to 770 this message. 772 Note also that not all of a client's viewers with access to the item 773 will be named in ViewerNames: some of them may have not enabled 774 notifications. 776 8.5.15 Modification 778 Opcode: 0x0F 780 ContextName: String 781 ViewerNames: vector of String 782 ItemName: String 783 ItemProperties: vector of name-value pairs 785 Provides a notification to the named viewers that the named properties 786 of the named item have been modified (using a Modify command). 788 The default-flag byte must be cleared (value of 0x00). 790 The ViewerNames are the viewers declared by this client that are 791 receiving this notification, not all viewers receiving the 792 notification. In particular, note that ViewerNames in this message is 793 not identical to ViewerNames in the Modify request that gives rise to 794 this message. 796 Note also that not all of a client's viewers with access to the item 797 will be named in ViewerNames: some of them may have not enabled 798 notifications. 800 8.5.16 Deletion 802 Opcode: 0x10 804 ContextName: String 805 ViewerNames: vector of String 806 ItemName: String 807 ItemProperties: vector of String 809 Provides a notification to the named viewers that certain properties 810 of the named item have been deleted (using a Delete command). 812 The default-flag byte must be cleared (value of 0x00). 814 The ViewerNames are the viewers declared by this client that are 815 receiving this notification, not all viewers receiving the 816 notification. In particular, note that ViewerNames in this message is 817 not identical to ViewerNames in the Modify request that gives rise to 818 this message. 820 Not all of a client's viewers with access to the item will be named in 821 ViewerNames: some of them may have not enabled notifications. 823 8.5.17 OK 825 Opcode: 0x11 827 This is sent as an acknowledgement that a previous request was 828 successfully completed, without errors. All requests except List 829 Viewers and Fetch cause the server to reply OK if the request 830 completed successfully. 832 8.5.18 Error 834 Opcode: 0xFF 836 ContextName: String 837 Code: Cardinal 838 StringData: Vector of String 839 Explanation: String 841 Provides a machine-processable error code, some data providing further 842 context for the error, and a simple explanation that can be used for 843 debugging. The explanations provided here are typical examples, 844 rather than mandatory. Any such explanation provided by the server 845 MUST NOT be presented to a user except as debugging information. 846 Instead, the error code should be used to map to an appropriately 847 localized error message. 849 Error code StringData interpretation Explanation 851 1 Opcode value received, "Unrecognized Opcode" 852 as UTF-8 decimal representation 853 2 None "Not Authenticated" 854 3 Depends on authentication "Authentication 856 protocol Failed" 857 5 Item name "Not Authenticated to 858 Affect Item" 859 6 Viewer name "Not Authenticated to 860 Act As Viewer" 861 7 Viewer name "No Such Viewer" 862 8 Maximum bytes allowed in "Value Exceeded 863 value, as UTF8 representation Server's Maximum 864 Length" 865 9 Context name "No Such Context" 866 10 Allowed context names "Only These Contexts 867 Allowed" 868 11 Allowed item names "Only These Items 869 Allowed" 870 12 Allowed viewer names "Only These Viewers 871 Allowed" 873 9. Acknowledgements 875 SGAP is a descendant of NSTP [NSTP, DPM] and has benefited from John 876 Patterson's perspective in the design of that protocol. In addition, 877 comments and criticism by Rob Ullmann, Dave Mitchell, Sandeep Singhal, 878 Steve Foley, and Kamal Ayad have contributed greatly to improving the 879 design. Naturally, any remaining errors are the responsibility of the 880 author. 882 10. References 884 [DPM] Mark Day, John F. Patterson, and David Mitchell. "The 885 Notification Service Transfer Protocol (NSTP): Infrastructure for 886 Synchronous Groupware." Computer Networks and ISDN Systems, 1997. 888 [NSTP] Mark Day, John Patterson, Jakov Kucan, David Mitchell, Wei-Meng 889 Chee. The Notification Service Transfer Protocol. Lotus Workgroup 890 Technologies Technical Report 96-08, 1996. 892 [RFC-1034] Paul Mockapetris. "Domain Names -- Concepts and 893 Facilities." RFC-1034, November 1987. 895 11. Changes Made in Revision 1 897 a. Changed version number changed from 0x05 to 0x85. The top bit will be 898 set 899 for all future version numbers. This change enables SGAP and NSTP 900 packets to flow to a single server over a single connection. 902 b. Moved old Section 5 into Section 6. Old Section 6 rewritten, broken 903 into smaller subsections. 905 c. Contexts explained. 907 d. Added SGAP:MIME type. 909 e. Added Init message; renumbered opcodes. 911 f. Modified Declare message to allow the default behavior even when 912 using the long form of Declare. 914 g. Clarified that notifications are disabled and must be explicitly 915 enabled. 917 h. Added new error codes. 919 12. Author's Address 921 Mark Day 922 Lotus Development Corporation 923 55 Cambridge Parkway 924 Cambridge, MA 02142 925 USA 927 Mark_Day@lotus.com