idnits 2.17.1 draft-day-msd-00.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-27) 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 748 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 an Authors' Addresses Section. ** 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 121: '... on the size of values. A server MUST...' RFC 2119 keyword, line 304: '...e version number MUST be set to 0x05 i...' RFC 2119 keyword, line 309: '...he reserved byte MUST be set to 0x00 i...' RFC 2119 keyword, line 310: '...and MUST be ignored by implementations...' RFC 2119 keyword, line 329: '...lags, and the other bits MUST be zero....' (14 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 801 looks like a reference -- Missing reference section? 'NSTP' on line 797 looks like a reference -- Missing reference section? 'DPM' on line 793 looks like a reference Summary: 12 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: July 14, 1998 Lotus Development Corporation 4 Matrix Model for Selective Dissemination 6 draft-day-msd-00.txt 8 1. Status of this Memo 10 This document is an Internet-Draft. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its 12 areas, and its working groups. Note that other groups may also 13 distribute working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six 16 months and may be updated, replaced, or obsoleted by other 17 documents at any time. It is inappropriate to use Internet- 18 Drafts as reference material or to cite them other than as 19 "work in progress." 21 To view the entire list of current Internet-Drafts, please check 22 the "1id-abstracts.txt" listing contained in the Internet-Drafts 23 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 24 (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East 25 Coast), or ftp.isi.edu (US West Coast). 27 2. Abstract 29 The year-2000 problem (Y2K problem) is of increasing interest. Little 30 has been said about the relationship of Y2K to synchronous 31 groupware. We describe a matrix model of selective dissemination of 32 information to viewers of that information. The model is suitable for 33 some forms of synchronous groupware. 35 3. Contents 37 1. Status of this Memo 38 2. Abstract 39 3. Contents 40 4. Introduction 41 5. Properties 42 6. Protocol Model 43 7. Server-Server Protocol Not a Special Case 44 8. Special Server Behavior 45 9. Protocol Specification 46 9.1 Model 47 9.2 Summary of Messages 48 9.3 Body Encoding 49 9.3.1 Types 50 9.4 Messages 51 9.4.1 Declare 52 9.4.2 Create 53 9.4.3 Modify 54 9.4.4 Delete 55 9.4.5 Split Viewers 56 9.4.6 Merge Viewers 57 9.4.7 List Viewers 58 9.4.8 Viewer List 59 9.4.9 Fetch 60 9.4.10 Fetch Response 61 9.4.11 Enable 62 9.4.12 Disable 63 9.4.13 Creation 64 9.4.14 Modification 65 9.4.15 Deletion 66 9.4.16 OK 67 9.4.17 Error 68 10. Acknowledgements 69 11. References 71 4. Introduction 73 Synchronous collaboration in a network environment is determined by 74 the characteristics of people and how they work together. We have 75 found it useful to divide synchronous collaboration into three phases: 76 awareness, conversation, and sharing. A collaboration proceeds 77 through the phases in that order. Multiple overlapping and returning 78 sequences through this model are possible 80 i. Awareness: A user first becomes aware that other users, groups, or 81 resources of interest are available. Awareness is comparable to the 82 function of peripheral vision. 84 ii. Conversation: Having become aware of those others, the user starts 85 one or more conversations or conferences with those people (via 86 various media, such as voice, text, or video). 88 iii. Sharing: Being engaged in conversations, the user finds it useful 89 to share documents or other objects. Such sharing adds value in two 90 ways. First, it allows for richer collaboration than is possible with 91 conversation alone, such as jointly editing a document or playing a 92 real-time game. Second, it allows for conversational ellipsis: for 93 example, a gesture at a sentence accompanied by the phrase "I don't 94 that starts with 'Synchronous.'" 96 The Simple General Awareness Protocol (SGAP) is intended to be used 97 primarily for awareness, the first phase of the process. SGAP is not 98 intended as a mechanism for conversation or sharing; there are a 99 number of technologies that can be used for various forms of 100 conversation and sharing, and relatively few that allow for the 101 features required of an awareness system. 103 In addition, the requirements in the two contexts are fundamentally 104 different. An awareness system involves the selective exposure of 105 small amounts of information to large numbers of others, with 106 relatively loose consraints on latency. A conversation and sharing 107 system involves the sharing of large amounts of information 108 (high-bandwidth channels) among a relatively small group, with 109 relatively tight constraints on latency. To use a telephone-system 110 analogy, we consider awareness to be largely "signalling" for the 111 higher-bandwidth "connection" represented by the conversations and 112 sharing. 114 5. Properties 116 A property is the smallest of these units. A property consists of a 117 name, a type, and a value. Both the name and type of a property are 118 UTF-8 encoded text strings, with relatively few restrictions on the 119 form of the strings. A property's value is zero or more bytes of 120 arbitrary data. Architecturally, a value may be up to 4 gigabytes, but 121 servers may set a smaller bound on the size of values. A server MUST 122 NOT break the connection only because a client sends an 123 excessively-large value. Instead, the server must send an error 124 message, then count bytes past the offending element and continue with 125 the next usable request. 127 6. Protocol Model 129 Conceptually, a server implements a matrix, with a row for each 130 distinct item to be shared and a column for each distinct viewer with 131 whom that information should be shared. The intersection of a column 132 and row is called a cell, and corresponds to the view of an item 133 delivered to a viewer. 135 Each item has a distinct item name. The item name is used simply as an 136 identifier for the item; in general, there are no additional semantics 137 (however, a small number of item names are significant to the 138 server). For example, "www.lotus.com" is different from 139 "http://www.lotus.com", though both are legal item names, as is any 140 UTF-8 encoded string of non-zero length (such as "Bill Clinton" or 141 "X%66 52 *$#"). 143 Each viewer also has a distinct viewer name. Again, the viewer name is 144 used simply as an identifier for the viewer; in general, there are no 145 additional semantics (again, a small number of viewer names are 146 significant to the server). 148 Although distinct items have distinct names, and distinct viewers have 149 distinct names, it is acceptable for an item and a viewer to have the 150 same name. Indeed, such name-sharing is the typical case. 152 The protocol assumes an authenticated connection between client and 153 server. The authenticated client entity is referred to as the 154 principal. 156 A client declares its use of a given name. Usually, such a declaration 157 means that the client both acts as the item with that name, and acts 158 as the viewer with that name; however, a client may optionally decline 159 one of the roles when it declares a name. The server may refuse to 160 allow a given principal to declare particular names, or may limit the 161 number of names that a given principal may declare, or may require 162 that a given principal use one of a restricted set of names. 164 A client declared as a given item can affect (change the properties 165 of) the row corresponding to that item. A client can only affect a row 166 if it has declared itself as that item. A client declared as a given 167 viewer can see (get the values of) the column corresponding to that 168 viewer. A client can only see a column if it has declared itself as 169 that viewer. 171 A client may enable or disable notifications on any item that it can 172 see. When notifications are enabled on an item, any change in the 173 properties of that item cause a notification message to be sent to 174 that client. 176 There is a special viewer column representing the default viewer. This 177 column does not have an associated viewer name, and accordingly can 178 never be directly accessed by a viewer. However, a client declared as 179 an item can determine which properties are in the default column for 180 that item, as well as determining which viewer names actually map to 181 the default column for that item. 183 The default-viewer column allows the possibility of both 184 default-accessible and default-inaccessible sharing of 185 information. For a default-accessible item, the item's value appears 186 in the default column's cell. Viewers to be excluded are named 187 explicitly, with no value (or substitute values) appearing in the 188 cells of those columns. For a default-inaccessible item, no value 189 appears in the default column's cell. Viewers who can access the item 190 are named explicitly, with the appropriate value appearing in the 191 cells. 193 A single client-to-server transport connection can carry out commands 194 on behalf of an arbitrary number of items and viewers. In the case of 195 a "buddy list," the expected behavior is to act on behalf of a single 196 item and a single viewer, both representing the person using the 197 client. 199 7. Server-Server Protocol Not a Special Case 201 Multiple servers can coordinate their state using the existing 202 protocol. The protocol allows both a "publish" model and a "subscribe" 203 model, favoring neither over the other. 205 Consider a server P that has some items (x,y,z) being updated by 206 clients. To "publish" those items and make them available to Q's 207 clients, P connects to another server Q and declares the names 208 (x,y,z). From Q's perspective, P is just another client (although P's 209 authentication to Q likely establishes that P's principal has more 210 privileges than the typical client). 212 Correspondingly, to "subscribe" to those items, a third server R can 213 connect to P and declare the names (x,y,z), choosing to be only in the 214 viewer role on those names. 216 Although SGAP supports the publication or subscription of items across 217 multiple servers, the protocol does not specify how clients or servers 218 arrange for such publication or subscription to take place. Note that 219 there is no mechanism in the protocol that would either prevent or 220 detect a request loop among servers. 222 8. Special Server Behavior 224 Some properties provide information to the server about how to treat 225 an item. For example, some items should be deleted if the reponsible 226 client is disconnected, while others should persist; this difference 227 in behavior is encoded in one or more special properties understood by 228 the server. 230 The properties understood by a server are collectively called the 231 server schema. Server schemas are defined independently of the 232 protocol. However, the mechanism to determine the schema of a server 233 is fixed by the protocol. 235 The server schema of a given server is exposed as the item 236 named "SGAP:Schema-Root". Within that item, the properties named 237 "SchemaName" and "SchemaVersionNumber" are guaranteed to be 238 defined. The value of SchemaName is a UTF-8 encoded text string. The 239 value of SchemaVersionNumber is a 4-byte array, representing an 240 unsigned integer in network order. 242 9. Protocol Specification 244 9.1 Model 246 We consider an awareness service to be a map: 248 context X viewer name X item name -> property* 250 That is, for each triplet of , there is 251 a collection of zero or more properties. 253 9.2 Summary of Messages 255 In general, messages are carried via a reliable bytestream transport, 256 such as TCP. The following table summarizes the protocol messages and 257 their function. 259 Message Meaning 261 Declare Claim right to act on behalf of viewers 262 and/or items 263 Create Create new properties of an item exposed 264 to a viewer 265 Modify Modify the properties of an item exposed to 266 a viewer 267 Delete Delete the properties of an item exposed to 268 a viewer 269 Split Viewers Inform server that these viewers should see a 270 private (non-default) view of the item 271 Merge Viewers Inform server that these viewers should see the 272 default view of the item 273 List Viewers Get the names of viewers with private views 274 of an item 275 Viewer List Reply containing the names of viewers with 276 private views of an item 277 Fetch Get the properties provided to a viewer for 278 a set of items 279 Fetch Reponse Reply containing the properties for a set 280 of items 281 Enable Allow delivery of change notifications 282 Disable Suppress delivery of change notifications 283 Creation Notify of property creation 284 Modification Notify of property modification 285 Deletion Notify of property deletion 286 OK Acknowledge successful completion 287 Error Explain an error condition 289 The header of each message consists of a one-byte version number, a 290 one-byte opcode, one reserved byte, one default-flag byte, and a 291 4-byte length (in network order) of the following body in bytes, not 292 including the header or length itself. 294 +--------------+--------------+--------------+--------------+ 295 | 0x05 | opcode | 0x00 | default-flag | 296 +--------------+--------------+--------------+--------------+ 297 | length in bytes of following body | 298 +-----------------------------------------------------------+ 299 | body | 300 + . + 301 | . | 302 + . + 304 The version number MUST be set to 0x05 in this version of the protocol. 306 The opcode identifies the operation to be carried out in response to 307 the message. 309 The reserved byte MUST be set to 0x00 in this version of the protocol 310 and MUST be ignored by implementations. 312 The default-flag byte is used to indicate whether an operation applies 313 to the default cell(s) and/or all other cell(s). The flag is needed 314 because the default cells have no name: they correspond to every 315 viewer for which the server does not have a viewer-specific cell. In 316 addition, there is no way to name "all viewers other than default." 318 The following table lists the acceptable values for the default-flag 319 byte and their interpretation. 321 0x00 All viewer cells to which the operation applies are explicitly 322 named in the body. 323 0x01 The default viewer cell(s) are affected in addition to any cells 324 explicitly named in the body. 325 0x02 All cells except the default viewer cell(s) are affected. 326 0x03 All cells of the item(s) are affected. 328 No other values are legal. That is, the two low-order bits serve as 329 flags, and the other bits MUST be zero. 331 The default-flag byte is only used for a few message types, but there 332 would be no advantage to putting its flags into the body of those 333 messages. Neither the version number nor the opcode requires more 334 than a single byte, while it is advantageous for some machines to have 335 the 4-byte length aligned on a 4-byte boundary. So the default-flag 336 byte uses a byte that would otherwise be "wasted" in the header. 338 9.3 Body Encoding 340 A "vector" is encoded as a 4-byte unsigned integer in network order, 341 followed by the number of elements determined by that integer's value, 342 followed by 0 to 3 padding bytes. The number of padding bytes is 343 chosen so that the entire vector's length in bytes is a multiple of 344 4. Padding bytes are chosen to alternate between the values 0xAC and 345 0xDC. Implementations MUST ignore the value of padding bytes received. 347 A "String" is a vector of bytes. The bytes contain the UTF8 encoding 348 of character data. There is no null character terminating the string. 350 A "Property" is two Strings (name and type) followed by a vector of 351 bytes. In contrast to the Strings, the value vector may contain 352 arbitrary bytes, including values that are not allowed in a UTF-8 353 encoding. A Property is considered to be a single element. Thus, a 354 vector of Properties starts with a count of the number of Properties, 355 not the (three times larger) number of component vectors. 357 9.3.1 Types 359 The following type names and meanings are defined by the 360 protocol. 362 Type Name bytes in value Interpretation 364 SGAP:boolean 1 0x00 = false 365 0x01 = true 366 other values illegal 367 SGAP:ternary 1 0x00 = no 368 0x01 = yes 369 0x02 = maybe 370 SGAP:byte 1 arbitrary byte value 371 SGAP:int 4 32-bit 2's complement 372 integer in network order 373 SGAP:unsigned 4 32-bit unsigned integer 374 in network order 375 SGAP:string arbitrary UTF-8 encoded 376 SGAP:javastring 2+arbitrary UTF-8 encoded with 16-bit 377 prefix count 378 SGAP:cstring arbitrary ASCII with null terminator 379 SGAP:xml-1.0 arbitrary expression in XML 1.0 syntax 381 Other type names MAY be defined. Such type names SHOULD take the form 382 of an internet domain name [RFC-1034] identifying the naming entity, 383 followed by a colon ":", then the type name assigned by the naming 384 entity. Thus "lotus.com:DominoInteger", "ietf.org:IANARegistryEntry", 385 and "cl.cam.ac.uk:2@3" are all acceptable type names. 387 9.4 Messages 389 For each message, we present information in the following form (using 390 the Split Viewers message as an example): 392 9.4.5 Split Viewers 394 Opcode: 0x05 396 ContextName: String 397 ItemName: String 398 ViewerNames: vector of String 400 Indicates to the server that the named viewers are not to be 401 given the default viewer cell for the named item in the named 402 context. The default-flag byte must be cleared (value of 403 0x00). 405 The numbered section heading gives the name of the message (Split 406 Viewers, in this case). 408 The next line gives the value for the opcode byte, in 409 hexadecimal. Accordingly, a message with the opcode 5 is a Split 410 Viewers message. 412 The next lines give the encoding of the message's body. The body of a 413 Split Viewers consists of three elements in an implicit sequence: a 414 String, another String, and a vector of Strings. The names of the 415 elements serve as a clue to their function, and provide a way for the 416 explanatory text to refer to these elements. The names of elements 417 (such as "ContextName") are for explanation only and are not 418 explicitly represented in protocol messages. 420 The final paragraph summarizes the function of the message and the 421 meaning of its elements, including any constraints on the values in 422 the body or in the header. 424 9.4.1 Declare 426 Opcode: 0x01 428 ContextName: String 429 Name: String 430 MultiNames: vector of NameDeclaration 432 where NameDeclaration is 434 DeclaredName: String 435 NameModifiers: vector of integer 437 Declares to the server that the client will use Name as its name. The 438 client can affect the item with that name and act as the viewer with 439 that name. 441 Name and MultiNames are mutually exclusive: if Name is a 442 non-zero-length String, MultiNames MUST be a zero-length vector. If 443 Name is a zero-length String, MultiNames MUST NOT be a zero-length 444 vector. 446 For each NameDeclaration in MultiNames, the DeclaredName MUST NOT be a 447 zero-length String. Implementations MUST reject requests in which the 448 same DeclaredName appears more than once. 450 Elements of NameModifiers can be any of the following: 452 0x1 "ItemOnly" the client may affect the named item but will not 453 act as the named viewer. 454 0x2 "ViewerOnly" the client may act as the named viewer but will 455 not affect the named item. 456 0x3 "Exclusive" the client insists that it is the only declarer 457 of this name in this form 459 An implementation MUST reject any request that includes both 460 "ItemOnly" and "ViewerOnly" in NameModifiers. 462 "Exclusive" alone means that no other client may affect the item by 463 that name or act as the viewer by that name. The item is 464 still potentially available to other viewers. 466 "Exclusive" and "ItemOnly" together mean that no other client may 467 affect the item by that name, although other clients may declare the 468 same name "ViewerOnly". 470 "Exclusive" and "ViewerOnly" together mean that no other client may 471 act as the viewer with that name, although other clients may declare 472 the same name "ItemOnly". 474 9.4.2 Create 476 Opcode: 0x02 478 ContextName: String 479 ItemName: String 480 ViewerNames: vector of String 481 NewProperties: vector of name-value pairs 483 Creates new properties contained within the named item in the named 484 context. Affects the cells determined by the combination of the 485 default-flag byte and ViewerNames. 487 A single create request takes place atomically. No client sees the 488 result of a partially executed create. 490 An implementation MUST reject the creation of a property that already 491 exists in any of the cells affected. 493 Causes create notifications to be delivered to viewers that have 494 enabled notifications. 496 9.4.3 Modify 498 Opcode: 0x03 500 ContextName: String 501 ItemName: String 502 ViewerNames: vector of String 503 NewProperties: vector of name-value pairs 505 Replaces the properties contained within the named item in the named 506 context. Affects the cells determined by the combination of the 507 default-flag byte and ViewerNames. 509 A single modify request takes place atomically. No client sees the 510 result of a partially executed modify. 512 An implementation MUST reject the modification of a property that does 513 not exist in any of the cells affected. 515 Causes modify notifications to be delivered to viewers that have 516 enabled notifications. 518 9.4.4 Delete 520 Opcode: 0x04 522 ContextName: String 523 ItemName: String 524 ViewerNames: vector of String 525 NewProperties: vector of name-value pairs 527 Deletes the properties contained within the named item in the named 528 context. Affects the cells determined by the combination of the 529 default-flag byte and ViewerNames. 531 A single delete request takes place atomically. No client sees the 532 result of a partially executed delete. 534 An implementation MUST reject the deletion of a property that does not 535 exist in any of the cells affected. 537 Causes delete notifications to be delivered to viewers that have 538 enabled notifications. 540 9.4.5 Split Viewers 542 Opcode: 0x05 544 ContextName: String 545 ItemName: String 546 ViewerNames: vector of String 548 Indicates to the server that the named viewers are not to be given the 549 default viewer cell for the named item in the named context. The 550 default-flag byte must be cleared (value of 0x00). 552 9.4.6 Merge Viewers 554 Opcode: 0x06 556 ContextName: String 557 ItemName: String 558 ViewerNames: vector of String 560 Indicates to the server that the named viewers are to be given the 561 default viewer cell for the named item in the named context. The 562 default-flag byte must be cleared (value of 0x00). 564 9.4.7 List Viewers 566 Opcode: 0x07 568 ContextName: String 569 ItemName: String 571 Requests a list of the names of named viewers (those viewers with 572 other than the default view of the named item). The default-flag byte 573 must be cleared (value of 0x00). 575 The server MUST reject this request if sent by any client that has not 576 succesfully declared itself as the named item. 578 9.4.8 Viewer List 580 Opcode: 0x08 582 ContextName: String 583 ItemName: String 584 Viewers: vector of String 586 The Viewer list is the list of explicitly named viewers for the object 587 named. All other viewers receive the default properties for that 588 object. Note that the server does not know or care whether there are 589 any actual differences between the properties in the default view cell 590 and the properties in other view cells. The default-flag byte must be 591 cleared (value of 0x00). 593 9.4.9 Fetch 595 Opcode: 0x09 597 ContextName: String 598 ViewerName: String 599 ItemNames: vector of String 600 AndEnable: vector of bytes 602 Requests the properties of the named items, on behalf of the named 603 viewer. The default-flag byte must be cleared (value of 0x00). Each 604 name in ItemNames MUST be distinct. 606 A single fetch request takes place atomically. No client sees the 607 result of a partially executed fetch. 609 If AndEnable is not a zero-length vector, then it MUST have the same 610 number of elements as ItemNames. Each byte MUST be either the value 611 0x00 (ignore) or 0x01 (enable). For each byte that has the value 612 "enable", the request enables change notifications immediately for the 613 item named in the corresponding position of ItemNames (see "Enable", 614 below). 616 9.4.10 Fetch Response 618 Opcode: 0x0A 620 ContextName: String 621 ViewerName: String 622 ObjectInfo: vector of ItemState 624 where ItemState is 626 ItemName: String 627 ItemProperties: vector of name-value pairs 629 Provides the properties of the named items, in response to a Fetch 630 request. The default-flag byte must be cleared (value of 0x00). 632 9.4.11 Enable 634 Opcode: 0x0B 636 ContextName: String 637 ViewerName: String 638 ItemName: vector of String 640 Enables the delivery of change notifications. After this command is 641 received, the server will deliver notifications to the named viewer 642 whenever any of the named items in the named context change in a way 643 that is visible to the viewer. The default-flag byte must be cleared 644 (value of 0x00). 646 Depending on special server behavior (see Section 8) the server may 647 deliver these notifications by a different channel rather than an 648 existing SGAP transport connection. For example, the server may use a 649 connectionless protocol such as UDP, or may open a server-to-client 650 TCP connection to deliver the notification. 652 [[ TBD: specify time limits and renewals. Also arrange for them to be 653 forwarded by outgoing proxy. ]] 655 9.4.12 Disable 657 Opcode: 0x0C 659 ContextName: String 660 ViewerName: String 661 ItemNames: vector of String 663 Disables the delivery of notifications of changes. After this command 664 is received, the server will not deliver any notifications to the 665 named viewer from changes to the named items. The default-flag byte 666 must be cleared (value of 0x00). 668 After issuing a disable request, a client must be prepared to receive 669 some number of spurious (late) notifications and silently discard them. 671 9.4.13 Creation 673 Opcode: 0x0D 675 ContextName: String 676 ViewerNames: vector of String 677 ItemName: String 678 ItemProperties: vector of name-value pairs 680 Provides a notification to the named viewers that the named properties 681 have been created as part of the named item (using a Create command). 683 The default-flag byte must be cleared (value of 0x00). 685 The ViewerNames are the viewers declared by this client that are 686 receiving this notification, not all viewers receiving the 687 notification. In particular, note that ViewerNames in this message is 688 not identical to ViewerNames in the Create request that gives rise to 689 this message. 691 Note also that not all of a client's viewers with access to the item 692 will be named in ViewerNames: some of them may have not enabled 693 notifications. 695 9.4.14 Modification 697 Opcode: 0x0E 699 ContextName: String 700 ViewerNames: vector of String 701 ItemName: String 702 ItemProperties: vector of name-value pairs 704 Provides a notification to the named viewers that the named properties 705 of the named item have been modified (using a Modify command). 707 The default-flag byte must be cleared (value of 0x00). 709 The ViewerNames are the viewers declared by this client that are 710 receiving this notification, not all viewers receiving the 711 notification. In particular, note that ViewerNames in this message is 712 not identical to ViewerNames in the Modify request that gives rise to 713 this message. 715 Note also that not all of a client's viewers with access to the item 716 will be named in ViewerNames: some of them may have not enabled 717 notifications. 719 9.4.15 Deletion 721 Opcode: 0x0F 723 ContextName: String 724 ViewerNames: vector of String 725 ItemName: String 726 ItemProperties: vector of String 728 Provides a notification to the named viewers that certain properties 729 of the named item have been deleted (using a Delete command). 731 The default-flag byte must be cleared (value of 0x00). 733 The ViewerNames are the viewers declared by this client that are 734 receiving this notification, not all viewers receiving the 735 notification. In particular, note that ViewerNames in this message is 736 not identical to ViewerNames in the Modify request that gives rise to 737 this message. 739 Not all of a client's viewers with access to the item will be named in 740 ViewerNames: some of them may have not enabled notifications. 742 9.4.16 OK 744 Opcode: 0x10 746 This is sent as an acknowledgement that a previous request was 747 successfully completed, without errors. All requests except List 748 Viewers and Fetch cause the server to reply OK if the request 749 completed successfully. 751 9.4.17 Error 753 Opcode: 0xFF 755 ContextName: String 756 Code: Cardinal 757 StringData: String 758 Explanation: String 760 Provides a machine-processable error code, some data providing further 761 context for the error, and a simple explanation that can be used for 762 debugging. The explanations provided here are typical examples, 763 rather than mandatory. Any such explanation provided by the server 764 MUST NOT be presented to a user except as debugging information. 765 Instead, the error code should be used to map to an appropriately 766 localized error message. 768 Error code StringData interpretation Explanation 770 1 Opcode value received, "Unrecognized Opcode" 771 as UTF-8 decimal representation 772 2 None "Not Authenticated" 773 3 Depends on authentication "Authentication Failed" 774 protocol 775 5 Item name "Not Authenticated to 776 Affect Item" 777 6 Viewer name "Not Authenticated to 778 Act As Viewer" 779 7 Viewer name "No Such Viewer" 780 8 Maximum bytes allowed in "Value Exceeded 781 Server's 782 value, as UTF8 representation Maximum Length" 784 10. Acknowledgements 786 SGAP is a descendant of NSTP [NSTP, DPM] and has benefited from John 787 Patterson's perspective in the design of that protocol. In addition, 788 comments and criticism by Rob Ullmann, Dave Mitchell, and Sandeep 789 Singhal have contributed greatly to improving the design. 791 11. References 793 [DPM] Mark Day, John F. Patterson, and David Mitchell. "The 794 Notification Service Transfer Protocol (NSTP): Infrastructure for 795 Synchronous Groupware." Computer Networks and ISDN Systems, 1997. 797 [NSTP] Mark Day, John Patterson, Jakov Kucan, David Mitchell, Wei-Meng 798 Chee. The Notification Service Transfer Protocol. Lotus Workgroup 799 Technologies Technical Report 96-08, 1996. 801 [RFC-1034] Paul Mockapetris. "Domain Names -- Concepts and 802 Facilities." RFC-1034, November 1987.