PROPFIND
The PropFind DAV method is used to get the properties of the node. The property contains some of the packets of Presence Information, a collection of values, such as online status or display names of the represented PRINCIPAL. For RVP, the PROPFIND method is used to get its online status from the respective local servers of other Principals. This method can also be used to extract other properties that the RVP implementation may remain, such as the permanent contact list stored on the server.
The PROPFIND method retrieves the properties defined on the requested URL. Presentity submits the propFind XML element in the Request method body, which illustrates information being requested. Request specific attribute values, all attribute values, or a list of resource properties names are possible. Presentity must submit at least one property.
If an error occurs when retrieving properties, a corresponding error result must be included in the response. Request to retrieve an unsaved attribute value is an error and must be recorded. If a multi-state XML element is used in response, you must return an XML element containing the 404 Not Found status value.
Each response XML element must contain an HREF XML element that identifies the resource that defines the properties in the PROP XML element. As a flat list returns the result of the propfind request for the resource with internal members, the order in this list is not important.
Although the DAV allows the depth of PROPFIND to 0, 1 or "infinity", "infinity" is the default, but the RVP requires a depth header to zero. This is due to the difficulty of supporting other depths when the namespace is implemented in a distributed manner. If the depth header does not exist or the depth parameter is not zero, RVP Presence Services will return status code: 412 -PRecondition failed (prerequisite failed).
Example
The following example shows how to retrieve the display name properties of RVP Presentity.
>> request
PropFind / Instmsg / AliaseS / Deriks HTTP / 1.1
Host: im.example.com
RVP-Notifications-Version: 0.2
Rvp-from-principal: http://im.example.com/instmsg/aliases/deriks
DEPTH: 0
Content-Type: Text / XML
Content-Length: XXXX
XMLns: z = "http://schemas.microsoft.com/rvp/"> >> Response HTTP / 1.1 207 Multi-Status Content-Type: Text / XML Content-Length: XXXX RVP-Notifications-Version: 0.2 XMLns: z = "http://schemas.microsoft.com/rvp/"> Http://im.example.com/instmsg/aliases/deriks Derik Stenerson Proppatch The PropPatch DAV method is used to set the properties of the node. For RVP, this method can be used to set the online state of Principal on the Presence Service or other properties that hold the RVP system. For example, when a presentity "login", Presentity issues a PropPATCH request to the local server of Presentity, requiring the online status property to "online". RVP introduces the concept of rental attributes. The rental attribute value will automatically reset to the default after a timeout. They can be used when the online state of the collaborator is implemented. For example, Presentity's online state can reset itself as offline, unless it is refreshed. This is useful if the client crashes, the network fails or other must reset the Presentity status as offline. Although the RVP implementation may prohibit rental specific attribute values, all RVP properties can have a rental value. Presentities gets the same way as the rental value is the same as that process the regular DAV property; the Presence Service is responsible for identifying and interpreting the lease value and enforces its behavior. If the requested timeout is not allowed by the RVP Presence Service management policy, the RVP Presence Service may reject the setting attribute value. The XML architecture allows a view identifier element to be specified in the PropPatch request and response, because a node may have multiple Presentities setting properties (ie, users logged in from multiple machines). This specification allows status changes to all Presentities and allows some states to be unique to a presentity. For example, if a Principal makes multiple presentities login, any status is changed to "Busy" or "Out to Lunch" will result in all of the present statute notifications. However, if a Presentity becomes offline or idle, other Presentity does not obtain the notification of this status change, and Principal is still online on different Presentity. A successful response will contain one when the PropPATCH request does not include the view identifier. This identifier is unique to any subsequent PropPATCH request for lease properties and specifying this view identifier. If all the lease properties with the view identifier expires, the identifier is no longer valid, nor should it be used. Example The following example sets a RVP Presentity's online status value to an online, and the time interval is one hour. Unless the property is subsequently reset by the Presentity, the Presence Service will turn the online value back to the line after an hour. >> Request: Proppatch / instimsg / aliases / deriks http / 1.1 Host: im.example.com RVP-Notifications-Version: 0.2 Rvp-from-principal: http://im.example.com/instmsg/aliases/derikscontent-type: text / xml Content-Length: XXXX XMLns: z = "http://schemas.microsoft.com/rvp/"> >> Response: HTTP / 1.1 207 Multi-Status RVP-Notifications-Version: 0.2 Content-Type: Text / XML Content-Length: XXXX XMLns: z = "http://schemas.microsoft.com/rvp/"> Http://im.example.com/instmsg/aliases/deriks 3600 Implementation consideration RVP Presentity uses the PropPatch method and the rental value to keep its online status properties online. Presentity uses some timeout values (ie, t) so that the Presence Service transforms back from the online status attribute after passing. If Principal is logged in in Presentity, Presentity should send another PropPATCH request before t expired, and obtain a new rental of T at the attribute to refresh the online status properties. Therefore, if T = 30 minutes, Presentity should issue another PropPATCH request at approximately 29 minutes. Otherwise, if Presentity issues a PropPatch request at 30 minutes, the new PropPatch request can reach the Presence Service after the first lease expires. In this case, any subscriber of the Principal online status (ie, all Watcher on its contact list) may get a false notification - a release given to the principal, and the other is released Give the Principal, logged in again. Several considerations determine the correct T value that should be used. If Presentity is Out of Contact, the Presence Service will not know that Presentity has collapsed and the online status properties of Principal have been online. Therefore, even if Principal is offline , T also restricts WatChers to continue to treat Principal as a "online" time interval. Keep the status of Watcher's contact list is "new", requiring T small - ideal cases close to zero. However, if Principal is logged in, Presentity must re-issue the PropPATCH request, and the time interval is less than t to keep an online state. Therefore, each login of Presentity consumes the resource of Presence Service because Presentity is effectively "ping" Presence Service, and the time interval is less than T. Even in idle state, this also generates network traffic. This load can be quite large if a Presence Service logs in to thousands of Presentities. To make the ping load get control, set T as big as possible so that each Principal's experience will not be downgraded. Note: The PING time interval used by Exchange 2000 Server Instant Messaging is 20 minutes. NOTIFY RVP Notify method, taken from GENA, send asynchronous notifications to the RVP node - that is, the receiver is notified. When a Watcher A changes Subscribe requests to the property on another Principal B via the local server, Watcher A will receive the Notify request for the property changes on Principal B. Note: The notification XML element in the request body contains the notification data. A Notify message can also be issued without establishing an earlier subscription. For example, assume that any entity can send a Notify message to a group node (such as http://im.example.com/groups/rec-cycling); Group nodes do not need to be issued to any other node Subscribe request. In an intranet, the Notify message is usually used by the local server to send notifications to Instant Inboxes. The Notify message is also used by Presence Services to send online status changes to other Presence Services. Because the sender of the Notify message may require a confirmation to send, the successful response will be issued once the transmission is completed. In order to determine the sender of the Notify message, a new RVP-ACK-TYPE header will appear when the sending and request confirmation is satisfied. This header can contain the following fields. Singlehop is just when the NOTIFY message is initially received (ie, the local server), the sender requests confirmation. The Deepor senter only requested to confirm when one of the final goals receive Notify. One example of this method is that one of the required system administrators when the user sends an instant message to the principal or printer. The Deepand Sendant requests confirmation only when all final goals receive the Notify message. One example of this method is that the message is sent to a group or distribution list, and there are multiple WatChers that is waiting for the Notify message. In addition, in the Notify request, another header is RVP-Hop-Count. This is a value based on 1, specified to generate how many times have been forwarded. Client -> server rvp-hop-count = 1 Server -> Server RVP-Hop-Count = 2 Server -> Client RVP-Hop-Count = 3 NOTIFY methods use new RVP XML elements: Message, PropNotification, Notification-from, Notification-To, Contact, Description, Msgbody, and Mime-Data. Example This example states presentity http://im.example.com/instmsg/AliaseS/deriks how to send instant messages to Instant Inbox http://im.acMewidgets.com/instmsg/aliases/maxb. >> request Notify / instmsg / aliases / maxb http / 1.1 Host: im.acmewidgets.com RVP-Notifications-Version: 0.2 RVP-ACK-TYPE: Deepor Rvp-hop-count: 1 Rvp-from-principal: http://im.example.com/instmsg/aliases/deriks Content-Type: Text / XML Content-Length: XXXX XMLns: z = "http://schemas.microsoft.com/rvp/"> Http://im.example.com/instmsg/aliases/deriks Derik Stenerson http://im.acmewidgets.com/instmsg/aliases/maxb Max
Content-Type: Text / Plain; Charset = UTF-8 X-MMS-IM-Format: Fn = microsoft% 20Sans% 20serif; EF =; CO = 0; cs = 0; pf = 22 Session-id: {79fc61b5-1234-1234- 8A10-941F33CA4C90} Let's have lunch ]]]] >> Response HTTP / 1.1 200 Successful RVP-Notifications-Version: 0.2 This example illustrates how the Notify message is sent to Maxb when Deriks login. For the purpose of this example, Principal http://im.example.com/instmsg/aliases/deriks is located on the contact list http://im.acmewidgets.com/Users/maxb, and maxb has subscribed Deriks online status. >> request Notify / http / 1.1 Rvp-hop-count: 2 RVP-Notifications-Version: 0.2 Host: 128.1.1.11 Content-Length: XXXX Content-Type: Text / XML RVP-from-Principal: Im.Example.com XMLns: z = "http://schemas.microsoft.com/rvp/"> Http://im.example.com/instmsg/aliases/deriks http://im.acmewidgets.com/instmsg/aliases/maxb >> Response HTTP / 1.1 200 Successful RVP-Notifications-Version: 0.2 ACL The ACL method provides some additions to the XML architecture. Access Control List (ACL) is used to determine who can access and update information on nodes. For example, it limits Watcher to see if Presentity is online. The namespace of the RVP ACL is slightly different from the WebDAV ACL, because there are several elements that are not required, and several new elements have been added. The namespace is http://schemas.microsoft.com/rvp/acl/.
