Pull

Article
06/14/2010

The Enumeration Endpoint implements the Pull operation, which retrieves the set of objects returned by a query.

Parameters

Action Header

For more information, see WS-Enumeration specification.

Enumeration Context Element

According to the WS-Enumeration specification, an invocation of the Pull operation uses as input whatever was provided as the enumeration context in the response to the corresponding invocation of the Enumerate operation.

MaxElements Element

For more information, see WS-Enumeration specification.

Pull Adjustment Element

As an extension to the WS-Enumeration specification of the Pull operation, clients can use the optional <PullAdjustment> element to specify the index number of the starting data for the current Pull operationand also change the direction in which data items are to be pulled. The structure of the <PullAdjustment> element is defined by the following schema.

<?xml version='1.0' encoding='utf-8'?>
<xs:schema
  elementFormDefault='qualified'
  targetNamespace='https://schemas.microsoft.com/2006/11/ResourceManagement'
  xmlns:xs='http://www.w3.org/2001/XMLSchema'
  xmlns:rm='https://schemas.microsoft.com/2006/11/ResourceManagement'>
  <xs:simpleType name='EnumerationDirectionsType'>
    <xs:restriction 
      base='xs:string'>
    <xs:enumeration 
      value='Forwards' />
    <xs:enumeration 
      value='Backwards' />
    </xs:restriction>
  </xs:simpleType>
  <xs:complexType
    name='PullAdjustmentType'>
    <xs:sequence>
       <xs:element
         name='StartingIndex'
         minOccurs='0'
         maxOccurs='1'
         nillable='false'
         type='xs:integer'/>
        <xs:element
          name='EnumerationDirection'
          minOccurs='1'
          maxOccurs='1'
          nillable='false' 
          type='rm:EnumerationDirectionsType' />
      </xs:sequence>
    </xs:complexContent>
  </xs:complexType>
  <xs:element
    name='PullAdjustment'
    nillable='true'
    type='rm:PullAdjustmentType' />
</xs:schema>

The elements of this structure are described as follows.

Element	Description
StartingIndex	The index number of a particular object in a collection of objects that match the query from which to start adding objects to a batch.
EnumerationDirection	The direction in which objects are to be added to the batch. Forwards: Proceeds through the collection of objects that math the query, from the current object toward the end of the collection. Backwards: Proceeds through the collection from the current object toward the beginning of the collection.
PullAdjustment	Combines a starting index and an enumeration direction.

StartingIndex

The index number of a particular object in a collection of objects that match the query from which to start adding objects to a batch.

EnumerationDirection

The direction in which objects are to be added to the batch.

Forwards: Proceeds through the collection of objects that math the query, from the current object toward the end of the collection.

Backwards: Proceeds through the collection from the current object toward the beginning of the collection.

PullAdjustment

Combines a starting index and an enumeration direction.

Return Value

Action Header

For more information, see WS-Enumeration specification.

Items Element

A successful invocation of the Pull operation will return, as sub-elements to the WS-Enumerate <Items> element, XML representations of the requested objects. The XML representations of the objects may also be structured to comply with any valid extension of that XML Schema.

Example

The following code example shows invoking the Pull operation without using any extensions.

<s:Envelope 
  xmlns:s=‘http://www.w3.org/2003/05/soap-envelope' 
  xmlns:wsa=‘https://schemas.xmlsoap.org/ws/2004/08/addressing' 
  xmlns:wsen=‘https://schemas.xmlsoap.org/ws/2004/09/enumeration'
  xmlns:wsc=‘https://schemas.microsoft.com/ws/2006/05/context'
  xmlns:rm=‘https://schemas.microsoft.com/2006/11/ResourceManagement'>
  <s:Header>
    <wsa:ReplyTo>
     <wsa:Address> 
       https://www.contoso.com/sender
     </wsa:Address>
    </wsa:ReplyTo>
    <wsa:To> 
      https://www.contoso.com:5725/IdentityManagementService/Enumeration
    </wsa:To>
    <wsa:Action>
      https://schemas.xmlsoap.org/ws/2004/09/enumeration/Pull
    </wsa:Action>
    <wsa:MessageID>
      uuid:00000000-0000-0000-C000-000000000046
    </wsa:MessageID>
    <rm:ResourceManagement s:mustUnderstand=“true"/>
  </s:Header>
  <s:Body>
    <wsen:Pull>
      <wsen:EnumerationContext> 
        <rm:Count>1</rm:Count> 
        <rm:CurrentIndex>0</rm:CurrentIndex>
        <rm:EnumerationDirection>Forwards</rm:EnumerationDirection> 
        <rm:Expires>12/31/9999 11:59:59 PM</rm:Expires> 
        <rm:Filter>/ma-data</rm:Filter> 
        <rm:LocalePreferences xsi:nil="true" /> 
        <rm:Selection xsi:nil="true" /> 
        <rm:Sorting xsi:nil="true" /> 
      </wsen:EnumerationContext>
      <wsen:MaxElements>
        10
      </wsen:MaxElements>
    </wsen:Pull>
  </s:Body>
</s:Envelope>

The following code example shows invoking the Pull operation that uses extensions.

<s:Envelope 
  xmlns:s=‘http://www.w3.org/2003/05/soap-envelope' 
  xmlns:wsa=‘https://schemas.xmlsoap.org/ws/2004/08/addressing' 
  xmlns:wsen=‘https://schemas.xmlsoap.org/ws/2004/09/enumeration'
  xmlns:wsc=‘https://schemas.microsoft.com/ws/2006/05/context'
  xmlns:rm=‘https://schemas.microsoft.com/2006/11/ResourceManagement'>
  <s:Header>
    <wsa:ReplyTo>
     <wsa:Address> 
       https://www.contoso.com/sender
     </wsa:Address>
    </wsa:ReplyTo>
    <wsa:To> 
      https://www.contoso.com:5725/IdentityManagementService/Enumeration
    </wsa:To>
    <wsa:Action>
      https://schemas.xmlsoap.org/ws/2004/09/enumeration/Pull
    </wsa:Action>
    <wsa:MessageID>
      uuid:00000000-0000-0000-C000-000000000046
    </wsa:MessageID>
    <rm:ResourceManagement s:mustUnderstand=“true"/>
  </s:Header>
  <s:Body>
    <wsen:Pull>
      <wsen:EnumerationContext> 
        <rm:Count>1</rm:Count> 
        <rm:CurrentIndex>0</rm:CurrentIndex>
         <rm:EnumerationDirection>Forwards</rm:EnumerationDirection> 
        <rm:Expires>12/31/9999 11:59:59 PM</rm:Expires> 
        <rm:Filter>/ma-data</rm:Filter> 
        <rm:LocalePreferences xsi:nil="true" /> 
        <rm:Selection xsi:nil="true" /> 
        <rm:Sorting xsi:nil="true" /> 
      </wsen:EnumerationContext>
      <wsen:MaxElements>
        10
      </wsen:MaxElements>
      <rm:PullAdjustment>
        <rm:StartingIndex>20</rm:StartingIndex>
        <rm:EnumerationDirection>Forwards</rm:EnumerationDirection>
      </rm:PullAdjustment>
    </wsen:Pull>
  </s:Body>
</s:Envelope>

The following code example shows invoking the Pull operation using a <PullAdjustment> element.

<s:Envelope 
  xmlns:s=‘http://www.w3.org/2003/05/soap-envelope' 
  xmlns:wsa=‘https://schemas.xmlsoap.org/ws/2004/08/addressing'
  xmlns:wsen=‘https://schemas.xmlsoap.org/ws/2004/09/enumeration'
  xmlns:rm=‘https://schemas.microsoft.com/2006/11/ResourceManagement'>
  <s:Header>
    ...
    <wsa:To> 
      http://www.woodgrove.com:5725/IdentityManagementService/Enumeration
    </wsa:To>
    <wsa:Action>
      https://schemas.xmlsoap.org/ws/2004/09/enumeration/Pull
    </wsa:Action>
    ...
    <rm:ResourceManagement s:mustUnderstand=“true"/>
  </s:Header>
  <s:Body>
    <wsen:Pull>
      <wsen:EnumerationContext> 
        <rm:Count>1</rm:Count> 
        <rm:CurrentIndex>0</rm:CurrentIndex> 
        <rm:EnumerationDirection>Forwards</rm:EnumerationDirection> 
        <rm:Expires>12/31/9999 11:59:59 PM</rm:Expires> 
        <rm:Filter>/ma-data</rm:Filter> 
        <rm:LocalePreferences xsi:nil="true" /> 
        <rm:Selection xsi:nil="true" /> 
        <rm:Sorting xsi:nil="true" /> 
      </wsen:EnumerationContext>
      <rm:PullAdjustment>
        <rm:StartingIndex>20</rm:StartingIndex>
        <rm:EnumerationDirection>Forwards</rm:EnumerationDirection>
      </rm:PullAdjustment>
    </wsen:Pull>
  </s:Body>
</s:Envelope>

The following code example shows a response to a successful Pull operation.

<s:Envelope 
  xmlns:s=‘http://www.w3.org/2003/05/soap-envelope' 
  xmlns:wsa=‘https://schemas.xmlsoap.org/ws/2004/08/addressing' 
  xmlns:wsen=‘ https://schemas.xmlsoap.org/ws/2004/09/enumeration' 
  xmlns:wsc=‘https://schemas.microsoft.com/ws/2006/05/context'
  xmlns:rm=‘https://schemas.microsoft.com/2006/11/ResourceManagement' >
  <s:Header>
    <wsa:To>
      https://www.contoso.com/sender
    </wsa:To>
    <wsa:Action>https://schemas.xmlsoap.org/ws/2004/09/enumeration/PullResponse
    </wsa:Action>
    <wsa:MessageID>
      uuid:0000010e-0000-0000-C000-000000000048
    </wsa:MessageID>
    <wsa:RelatesTo>
      uuid:00000000-0000-0000-C000-000000000048
    </wsa:RelatesTo>
  </s:Header>
  <s:Body>
  <wsen:EnumerationContext> 
    <rm:Count>1</rm:Count> 
    <rm:CurrentIndex>0</rm:CurrentIndex> 
    <rm:EnumerationDirection>Forwards</rm:EnumerationDirection> 
    <rm:Expires>12/31/9999 11:59:59 PM</rm:Expires> 
    <rm:Filter>/ma-data</rm:Filter> 
    <rm:LocalePreferences xsi:nil="true" /> 
    <rm:Selection xsi:nil="true" /> 
    <rm:Sorting xsi:nil="true" /> 
  </wsen:EnumerationContext>
    <wsen:Items>
      <rm:ma-data>                     
        <rm:ObjectType>ma-data</rm:ObjectType> 
        <rm:ObjectID> 
          urn:uuid:fa14aafd-d74b-4833-bd94-94c96ee1b278 
        </rm:ObjectID> 
        <rm:DisplayName>AD Management Agent</rm:DisplayName> 
        <rm:CreatedTime>2009-01-20T23:28:40.207</rm:CreatedTime> 
        <rm:Creator> 
          urn:uuid:23dbfb6c-557f-48d1-ac38-6d570ddbe189 
        </rm:Creator> 
      </rm:ma-data>
    </wsen:Items>
  </s:Body>
</s:Envelope>

Pull

Parameters

Action Header

Enumeration Context Element

MaxElements Element

Pull Adjustment Element

Return Value

Action Header

Items Element

Example

See Also

Concepts

Additional resources