GrooveEvents.ReadExtended Operation

The ReadExtended operation reads all events in the queue up to the specified sequence number. Optionally, you can use it to remove events that were read from the queue.

HTTP Post URL

The HTTP Post URL targets the service. This is a top-level HTTP Post URL that you supply directly; it is not returned as a value by another operation.

Input Message Header

GrooveRequestHeader specifies information common to all Groove Web Services, including the Groove Identity URL and the Groove Request key.

Input Message Parameters

<CallbackURI />
<Sequence />
<IncludeSources />
<DeleteEvents />
Element Data type Description

CallbackURI

xs:anyURI

Identifies the subscription by the CallbackURI specified in the GrooveSubscriptions.Create or GrooveSubscriptions.CreateAggregated2 operation. The CallbackURI must start with "dpp://localhost".

Sequence

xs:long

The sequence number of the last event to be read. All events from the beginning of the queue up to the sequence number specified are returned. To read all events in the queue, set sequence to zero.

IncludeSources

xs:boolean

If TRUE, the list of event sources will be included in the output. Otherwise it will not.

DeleteEvents

xs:boolean

If DeleteEvents is TRUE, read events will be deleted from the event queue. Otherwise the events will be retained in the queue. In the latter case, use Delete to delete read events after they have been successfully received.

Output Message Header

GrooveResponseHeader specifies the Response key.

Return Value

<ReadExtendedResult />
Element Data type Description

ReadExtendedResult

ExtendedEventData

Contains summary information about the events in the queue and a list of events.

Remarks

If very high reliability in reading events is required in your application, set DeleteEvents to FALSE. Then after processing the events, use the GrooveEvents.Delete operation to remove events from the queue explicitly. This increases reliability because it grants you the ability to reread events if the read failed to complete for any reason.

Note

If the event queue is empty, a call to ReadExtended returns no events. In this case, the EventList and the EventQueueSummary.EventSources elements are returned as nulls rather than as 0-length arrays. Consequently, an application should check if these elements are defined before accessing them. Alternatively, an application can check if EventQueueSummary.Count is greater than zero before accessing EventList.

Note

If you are calling the Read operation in a Microsoft Visual Studio® 2005 project and get a SOAP exception when there are one or more events, check that you have included the GrooveEventData.vb or GrooveEventData.cs file in your project. See Creating Groove Web Services Projects in Visual Studio 2005 for instructions on how to add this file to your project.

See Also

Reference

GrooveEvents Web Service
GrooveEvents.Delete Operation
GrooveEvents.Delete Operation
GrooveSubscriptions Web Service

Concepts

Handling Groove Web Services Events