Subject: New: 6.2.4.5 "search" Command

From: Doug Royer <[email-masked]>
Date: Sun, 17 Feb 2002 17:41:07 -0700

6.2.4.5 "search" Command

       "cmdid" (Optional see Section 6.2.2.1).

       "target" (see xxx)

       "latency" and "action" (Optional - see xxx)

   Response:

         One iCalendar message per "target" in the "select" element is
         returned (see Section xxx).

         One of the following "request-status" codes MUST be returned:

               2.0   - successfully executed the query

               2.0.9 - success, but some data could not be returned

               6.1   - Container not found

               6.3   - Bad args

         The data in each result contains an iCalendar object composed
         of all the selected components.  Only "REQUEST-STATUS"
         and the properties mentioned in the "SELECT" clause of the
QUERY
         are included in the components. Each iCalendar object is
         tagged with the TARGET property and optional CMDID property.

   Searching for Events

   In the example below events on March 10,1999 between 080000Z and
   190000Z are read.  In this case only 4 properties for each event are
   returned.  Two calendars are specified.  Only booked (vs scheduled)
   entries are to be returned.

   C: MSG 1 13 . 12507 378
   C: Content-Type: application/cap+xml
   C:
   C: <search cmdid="search01" target="relcal2,relcal3"/>
   C:  <![CDATA[
   C: BEGIN:VCALENDAR
   C: VERSION:2.0
   C: METHOD:SEARCH
   C: CMDID:search01
   C: TARGET:relcal2,relcal3
   C: CMDID:search01
   C: BEGIN:VQUERY
   C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID
   C:  FROM VEVENT
   C:  WHERE DTEND   >= '19990310T080000Z'
   C:  AND DTSTART <= '19990310T190000Z'
   C:  AND METHOD  IS 'CREATE'
   C: END:VQUERY
   C: END:VCALENDAR
   C: />]]>
   C: </search>
   C: END

   In this example the reply is spread across several BEEP ANS
   messages and each one fits inside of a BEEP payload. However each
   reply can be spread across multiple ANS messages.

   S: ANS 1 13 . 13211 803 0
   S: Content-Type: application/cap+xml
   S:
   S: <reply cmdid="search01" target="relcal2">
   S: <![CDATA[
   S: BEGIN:VCALENDAR
   S: VERSION:2.0
   S: METHOD:REPLY
   S: TARGET:relacal2
   S: CMDID:search01
   S: REQUEST-STATUS:2.0
   S: BEGIN:VEVENT
   S: DTSTART:19990310T090000Z
   S: DTEND:19990310T100000Z
   S: UID:abcxyz12345
   S: SUMMARY:Meet with Sir Elton
   S: REQUEST-STATUS:2.0
   S: END:VEVENT
   S: BEGIN:VEVENT
   S: DTSTART:19990310T130000Z
   S: DTEND:19990310T133000Z
   S: UID:abcxyz8999
   S: SUMMARY:Meet with  brave Sir Robin
   S: REQUEST-STATUS:2.0
   S: END:VEVENT
   S: END:VCALENDAR
   S: />]]>
   S: </reply>
   S: END

   S: ANS 1 14 . 14014 664 1
   S: Content-Type: application/cap+xml
   S:
   S: <reply cmdid="search01" target="relcal3">
   S: <![CDATA[
   S: BEGIN:VCALENDAR
   S: VERSION:2.0
   S: METHOD:REPLY
   S: CMDID:search01
   S: TARGET:relcal3
   S: REQUEST-STATUS:2.0
   S: BEGIN:VEVENT
   S: REQUEST-STATUS:2.0
   S: DTSTART:19990310T140000Z
   S: DTEND:19990310T150000Z
   S: UID:123456asdf
   S: SUMMARY:Summer Budget
   S: REQUEST-STATUS:2.0
   S: END:VEVENT
   S: END:VCALENDAR
   S: />]]>
   S: </reply>
   S: END

   S: NUL 1 15 . 14678 0
   S: END

   The return values are subject to VCAR filtering.  That is, if the
   request contains properties to which the UPN does not have access,
   those properties will not appear in the return values.  If the UPN
   has access to at least one property of the component, but has been
   denied access to all properties called out in the request, the
   response will contain a single REQUEST-STATUS property indicating the
   error.  That is, the VEVENT components will be the following:

   Here the request was successful, but the VEVENT contents
   were not accessable (4.1).

   S: ANS 1 13 . 14014 548 0
   S: Content-Type: application/beep+xml
   S:
   S: <reply cmdid="an-id" target="relcalid">
   S: <![CDATA[
   S: BEGIN:VCALENDAR
   S: METHOD:REPLY
   S: TARGET:relcalid
   S: CMIDID=an-id
   S: VERSION:2.0
   S: BEGIN:VEVENT
   S: REQUEST-STATUS:4.1
   S: END:VEVENT
   S: END:VCALENDAR
   S: />]]>
   S: </reply>
   S: END

   If the UPN has no access to any components at all, the response will
   simply be an empty data set.  The response looks the same if there
   the particular components did not exist.

   S: ANS 1 13 . 14014 502 0
   S: Content-Type: application/cap+xml
   S:
   S: <reply cmdid="an-id" target="relcalid">
   S: <![CDATA[
   S: BEGIN:VCALENDAR
   S: VERSION:2.0
   S: METHOD:REPLY
   S: CMDID:an-id
   S: TARGET:ralcalid
   S: REQUEST-STATUS:2.0
   S: END:VCALENDAR
   S: />]]>
   S: </reply>
   S: END

   Find alarms within a range of time for booked VEVENTs.

   C: MSG 1 15 . 14678 747
   C:
   C: <search cmdid="search02" target="relcal2,relcal3>
   C: <![CDATA[
   C: BEGIN:VCALENDAR
   C: VERSION:2.0
   C: METHOD:SEARCH
   C: TARGET:relcal2,relcal3
   C: CMDID:search02
   C: BEGIN:VQUERY
   C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID,VALARM
   C: FROM VEVENT,VTODO
   C: USING_COMPONENT VALARM x-alarm
   C:  WHERE x-alarm.TRIGGER >= '19990310T080000Z'
   C:  AND x-alarm.TRIGGER <= '19990310T190000Z'
   C:  AND METHOD = 'CREATE'
   C: END:VQUERY
   C: END:VCALENDAR
   C: />]]>
   C: </search>
   C: END

   Here no data was returned for relcal2:

   S: ANS 1 15 . 15426 511 0
   S: Content-Type: application/beep+xml
   S:
   S: <reply cmdid="search02" target="relcal2">
   S: <![CDATA[
   S: BEGIN:VCALENDAR
   S: VERSION:2.0
   S: TARGET:relcal2
   S: CMDID:search02
   S: METHOD:REPLY
   S: REQUEST-STATUS:X.Y		<- todo
   S: END:VCALENDAR
   C: />]]>
   C: </reply>
   C: END

   And here relcal3 did return some resuls:

   S: ANS 1 2 . 15937 734 1
   S: Content-Type: application/beep+xml
   S:
   S: <reply id="search02" target="relcal3">
   S: <![CDATA[
   S: BEGIN:VCALENDAR
   S: VERSION:2.0
   S: METHOD:REPLY
   S: TARGET:relcal3
   S: CMDID:search02
   S: REQUEST-STATUS:2.0
   S: BEGIN:VEVENT
   S: DTSTART:19990310T130000Z
   S: DTEND:19990310T133000Z
   S: UID:abcxyz8999
   S: SUMMARY:Meet with brave Sir Robin
   S: BEGIN:VALARM
   S: TRIGGER:19990310T132500Z
   S: SUMMARY:Almost time...
   S: ACTION:DISPLAY
   S: END:VALARM
   S: END:VEVENT
   S: END:VCALENDAR
   S: />]]>
   S: </reply>
   S: END

   And the end.

   S: NUL 1 15 . 16671 0
   S: END

   In this example [email-masked] reads a day's worth of events from
   cap://cal.example.com/opaqueid99. And the optional cmdid is not
   supplied as the CUA will not issue another command until this
   one completes.

   C: MSG 1 16 . 16671 668
   C: Content-Type: application/cap+xml
   C:
   C: <search target="opaqueid99"/>
   C: <![CDATA[
   C: BEGIN:VCALENDAR
   C: VERSION:2.0
   C: METHOD:SEARCH
   C: TARGET:opaqueid99
   C: BEGIN:VQUERY
   C: QUERY:SELECT DTSTART,DTEND,SUMMARY, UID FROM VEVENT
   C:  WHERE DTEND >= '19990714T080000Z'
   C:  AND DTSTART <= '19990715T080000Z'
   C: END:VQUERY
   C: END:VCALENDAR
   C: />]]>
   C: </search>
   C: END

   S: RPY 1 16 . 17359 751
   S: Content-Type: application/cap+xml
   S:
   S: <reply target="opaqueid99"/>
   S: <![CDATA[
   S: BEGIN:VCALENDAR
   S: VERSION:2.0
   S: METHOD:REPLY
   S: TARGET:opaqueid99
   S: REQUEST-STATUS:2.0
   S: BEGIN:VEVENT
   S: DTSTART:19990714T200000Z
   S: DTEND:19990714T210000Z
   S: UID:000444888929922
   S: SUMMARY:Blah blah
   S: END:VEVENT
   S: BEGIN:VEVENT
   S: UID:0034848098038888989443
   S: SUMMARY:meeting
   S: DTEND:19990714T233000Z
   S: DTSTART:19990714T223000Z
   S: END:VEVENT
   S: END:VCALENDAR
   S: />]]>
   S: </reply>
   S: END

   If there are multiple targets, each iCalendar reply is contained
   within its own <reply>.

   Stored VQUERY can be used by specifying the property QUERYID
   instead of QUERY.

   This matches all calendar store properties.  This MUST NOT return any
   VAGENDAs. IT would return all RELATED-TO properties.

        BEGIN:VCALENDAR
        VERSION:2.0
        METHOD:SEARCH
        TARGET:cap://bobo.ex.com
        BEGIN:VQUERY
        QUERY:SELECT * FROM VCALSTORE
        END:VQUERY
        END:VCALENDAR

   This will match all properties of the VAGENDA relcal4.  This MUST NOT
   return any components.

        BEGIN:VCALENDAR
        VERSION:2.0
        METHOD:SEARCH
        TARGET:cap://bobo.ex.com/relcal4
        BEGIN:VQUERY
        QUERY:SELECT * FROM VAGENDA
        END:VQUERY
        END:VCALENDAR

   This will fetch all stored VQUERYs. All stored queries MUST BE
   saved with a QUERYID.

        BEGIN:VCALENDAR
        VERSION:2.0
	METHOD:SEARCH
	TARGET:relcal4
        BEGIN:VQUERY
        QUERY:SELECT VQUERY.* FROM VQUERY.
        END:VQUERY
        END:VCALENDAR

---

From: Bernard Desruisseaux <[email-masked]>
Date: Thu, 21 Feb 2002 16:23:54 -0500

>    C: TARGET:relcal2,relcal3

Change to:

     C: TARGET:relcal2
     C: TARGET:relcal3

In draft-05, the TARGET property was only multi-instance
NOT multi-valued.  A multi-valued TARGET would make it
difficult to write restriction tables with "TARGET  1".

Regards,
Bernard
-- 
Bernard Desruisseaux                    mailto:[email-masked]
Research & Development                  Tel.  : +1 514 733-8500 x4213
Steltor                                 Fax   : +1 514 733-8878

---

From: Bernard Desruisseaux <[email-masked]>
Date: Thu, 21 Feb 2002 17:38:08 -0500

>    C: <search cmdid="search01" target="relcal2,relcal3"/>

The list of targets should be specified in XML
i.e., not as a comma separated list.

What about:

     C: <search cmdid="search01">
     C:   <target relcalid="relcal2"/>
     C:   <target relcalid="relcal3"/>

Regards,
Bernard

---

From: Doug Royer <[email-masked]>
Date: Thu, 21 Feb 2002 15:38:41 -0700

> difficult to write restriction tables with "TARGET  1".

Agreed.

---

From: Doug Royer <[email-masked]>
Date: Thu, 21 Feb 2002 16:51:37 -0700

> i.e., not as a comma separated list.

Why not just eliminate them from the transport command :-)
I was trying to keep the command down to wireless packet size
for wireless devices. They don't have a fixed size, but it
is always small.