StsAdapter.Query Method

  • Article

Performs queries against lists in Windows SharePoint Services.

Web Service: List Data RetrievalWeb Reference: http://<Site>/_vti_bin/DspSts.asmx

Syntax

<SoapHeaderAttribute("dataRoot")> _
<SoapDocumentMethodAttribute("http://schemas.microsoft.com/sharepoint/dsp/queryRequest", Use:=SoapBindingUse.Literal, ParameterStyle:=SoapParameterStyle.Bare)> _
<SoapHeaderAttribute("authentication")> _
<SoapHeaderAttribute("versions", Direction:=SoapHeaderDirection.InOut)> _
<SoapHeaderAttribute("request")> _
Public Function Query ( _
    queryRequest As QueryRequest _
) As XmlNode

Dim instance As StsAdapter
Dim queryRequest As QueryRequest
Dim returnValue As XmlNode

returnValue = instance.Query(queryRequest)

[SoapHeaderAttribute("dataRoot")] 
[SoapDocumentMethodAttribute("http://schemas.microsoft.com/sharepoint/dsp/queryRequest", Use=SoapBindingUse.Literal, ParameterStyle=SoapParameterStyle.Bare)] 
[SoapHeaderAttribute("authentication")] 
[SoapHeaderAttribute("versions", Direction=SoapHeaderDirection.InOut)] 
[SoapHeaderAttribute("request")] 
public XmlNode Query (
    QueryRequest queryRequest
)

Parameters

  • queryRequest
    A QueryRequest object that expresses a query in DSPQ (data retrieval service query) or Pass-Through format.

Return Value

A System.Xml.XmlNode object that contains the query result as follows, which includes a schema section and a data section:

<dsQueryResponse status="success" xmlns="http://schemas.microsoft.com/sharepoint/dsp">
  <x:schema xmlns:d="http://schemas.microsoft.com/sharepoint/dsp" xmlns:x="http://www.w3.org/2001/XMLSchema">
    <x:element name="List_Name">
      <x:complexType>
        <x:sequence maxOccurs="unbounded">
          <x:element name="List_Name_Row" minOccurs="0">
            <x:complexType>
              <x:sequence>
                <x:element name="ID" minOccurs="0" 
                  d:filterSupport="IsNull;IsNotNull;Eq;Neq;Lt;Gt;Leq;Geq;" 
                  d:displayName="ID" type="x:int" />
                <x:element name="Title" 
                  d:filterSupport="IsNull;IsNotNull;Eq;Neq;Lt;Gt;Leq;Geq;Contains;BeginsWith;" 
                  d:displayName="Title" type="x:string" />
                <x:element name="Modified" minOccurs="0" 
                  d:filterSupport="IsNull;IsNotNull;Eq;Neq;Lt;Gt;Leq;Geq;" 
                  d:displayName="Modified" type="x:dateTime" />
                <x:element name="Created" minOccurs="0" 
                  d:filterSupport="IsNull;IsNotNull;Eq;Neq;Lt;Gt;Leq;Geq;" 
                  d:displayName="Created" type="x:dateTime" />
                <x:element name="Author" minOccurs="0" 
                  d:filterSupport="IsNull;IsNotNull;Eq;Neq;Lt;Gt;Leq;Geq;" 
                  d:displayName="Created By">
                  <x:simpleType>
                    <x:restriction base="x:string">
                      <x:enumeration value="User_Name" />
                    </x:restriction>
                  </x:simpleType>
                </x:element>
                <x:element name="Editor" minOccurs="0" 
                  d:filterSupport="IsNull;IsNotNull;Eq;Neq;Lt;Gt;Leq;Geq;" 
                  d:displayName="Modified By">
                  <x:simpleType>
                    <x:restriction base="x:string">
                      <x:enumeration value="User_Name" />
                    </x:restriction>
                  </x:simpleType>
                </x:element>
                <x:element name="Attachments" minOccurs="0" 
                  d:filterSupport="IsNull;IsNotNull;Eq;Neq;" 
                  d:displayName="Attachments" type="x:boolean" />
                <x:element name="Number_Column" minOccurs="0" 
                  d:filterSupport="IsNull;IsNotNull;Eq;Neq;Lt;Gt;Leq;Geq;" 
                  d:displayName="Number_Column" type="x:float" />
              </x:sequence>
            </x:complexType>
          </x:element>
        </x:sequence>
      </x:complexType>
    </x:element>
  </x:schema>
  <List_Name >
    <List_Name_Row>
      <ID>1</ID>
      <Title>Value</Title>
      <Modified>2003-10-01T22:13:57</Modified>
      <Created>2003-10-01T22:13:57</Created>
      <Author>User_Name</Author>
      <Editor>User_Name</Editor>
      <Attachments>0</Attachments>
      <Number>100</Number>
    </List_Name_Row>
    <List_Name_Row>
      <ID>3</ID>
      <Title>Value</Title>
      <Modified>2003-10-01T22:14:23</Modified>
      <Created>2003-10-01T22:14:23</Created>
      <Author>User_Name</Author>
      <Editor>User_Name</Editor>
      <Attachments>0</Attachments>
      <Number>300</Number>
    </List_Name_Row>
  </List_Name>
</dsQueryResponse>

Remarks

Windows SharePoint Services does not support date-time values in XSD format, so time is ignored when the Query method is used.

The following table describes properties on the list or site object that is returned.

Name

Description

comparisonLocale

Optional. Specifies the default Windows locale identifier for a RowReturning object. This attribute is not defined for non-RowReturning objects.

contentType

Required. Specifies the content type of the object returned, which is always set to RowReturning for list objects and to TableReturning for site objects.

displayName

Optional. Specifies a string containing the friendly name for the list or site object. This property is always returned.

id

Required. A string that identifies the list or site object.

querySupport

Optional. Only the data retrieval service query (DSPQ) is supported.

serverParameters

Required. Always none for list and site objects.

SupportFiltering

Optional. Specifies whether filtering is supported. Always true for RowReturning objects. Although false for non-RowReturning objects, the unsafe and serverParameters fields can still be filtered.

SupportOrdering

Optional. Specifies whether ordering is supported. Always true.

supportPaging

Optional. The adapter supports forward-only paging as defined in data retrieval service protocol. When paging is requested in the query by specifying startPosition="" within the <dsQuery> element, the adapter generates an XML BLOB that can be used to retrieve the next batch of rows. This XML BLOB is returned through the next attribute in the <dsQueryResponse> element returned. The client can then set the startPosition attribute to this BLOB and repeat the original query to retrieve the next set of rows.

unsafe

Optional. Because all site and list objects are safe, this attribute is always set to false.

Example

The following code example uses the Query method to return items from a SharePoint list in which the Author column contains a specified name and the Number column contains values greater than a specified value.

Dim myStsAd As New Web_Reference_Name.StsAdapter()
myStsAd.Credentials = System.Net.CredentialCache.DefaultCredentials

Dim vArray(0) As String
vArray(0) = "1.0"
Dim myVersion As New Web_Reference_Name.Versions()
myVersion.version = vArray

myStsAd.versions = myVersion

Dim reqHeader As New Web_Reference_Name.RequestHeader()
reqHeader.document = Web_Reference_Name.DocumentType.content
reqHeader.method = Web_Reference_Name.MethodType.query

myStsAd.request = reqHeader

Dim myRequest As New Web_Reference_Name.QueryRequest()

Dim sQuery As New Web_Reference_Name.DSQuery()
sQuery.select = "/list[@id='{e5c6603b-0f6c-4bd9-8bb1-57c83854308b}']"

myRequest.dsQuery = sQuery

Dim spQuery As New Web_Reference_Name.DspQuery()
Dim xmlDoc = New System.Xml.XmlDocument()
Dim ndQuery As XmlElement = xmlDoc.CreateElement("And")
ndQuery.InnerXml = "<Eq><FieldRef Name='Author'/>" & _
    "<Value>Name</Value></Eq>" & _
    "<Gt><FieldRef Name='Number'/><Value>Number</Value></Gt>"
spQuery.Where = ndQuery

myRequest.dsQuery.Query = spQuery

Try

    Dim myNode As XmlNode = myStsAd.Query(myRequest)
    MessageBox.Show(myNode.OuterXml)

    Catch ex As System.Web.Services.Protocols.SoapException
        MessageBox.Show(ex.Message & ex.StackTrace)

End Try

Web_Reference_Folder.StsAdapter myStsAd = new Web_Reference_Folder.StsAdapter();
myStsAd.Credentials= System.Net.CredentialCache.DefaultCredentials;

string[] vArray = new string[1];
vArray[0] = "1.0";
Web_Reference_Name.Versions myVersion = new Web_Reference_Name.Versions();
myVersion.version = vArray;

myStsAd.versions = myVersion;

Web_Reference_Name.RequestHeader reqHeader = new Web_Reference_Name.RequestHeader();
reqHeader.document = Web_Reference_Name.DocumentType.content;
reqHeader.method = Web_Reference_Name.MethodType.query;

myStsAd.request = reqHeader;

Web_Reference_Name.QueryRequest myRequest = new Web_Reference_Name.QueryRequest();

Web_Reference_Name.DSQuery sQuery = new Web_Reference_Name.DSQuery();
sQuery.select = "/list[@id='{e5c6603b-0f6c-4bd9-8bb1-57c83854308b}']";

myRequest.dsQuery = sQuery;

Web_Reference_Name.DspQuery spQuery = new Web_Reference_Name.DspQuery();
XmlDocument xmlDoc = new System.Xml.XmlDocument();
XmlElement ndQuery = xmlDoc.CreateElement("And");
ndQuery.InnerXml = "<Eq><FieldRef Name=\"Author\"/>" +
    "<Value>Name</Value></Eq>" + 
    "<Gt><FieldRef Name=\"Number\"/>" + 
    "<Value>Number</Value></Gt>";
spQuery.Where = ndQuery;

myRequest.dsQuery.Query = spQuery;

try
{
    XmlNode myNode = myStsAd.Query(myRequest);
    MessageBox.Show(myNode.OuterXml);
}

catch (System.Web.Services.Protocols.SoapException ex)
{
    MessageBox.Show(ex.Message + ex.StackTrace);
}

SOAP Request Format

The following example shows the syntax of a SOAP request made through the data retrieval service. The placeholders shown must be replaced with actual values.

POST /_vti_bin/DspSts.asmx HTTP/1.1
Host: Server_Name
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://schemas.microsoft.com/sharepoint/dsp/queryRequest"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <authentication
      xmlns="http://schemas.microsoft.com/sharepoint/dsp">xml</authentication>
    <dataRoot      allowRemoteDataAccess="boolean" 
      xmlns="http://schemas.microsoft.com/sharepoint/dsp">
      <root>string</root>
    </dataRoot>
    <request      document="content or system" 
      method="query" 
      xmlns="http://schemas.microsoft.com/sharepoint/dsp" />
    <versions xmlns="http://schemas.microsoft.com/sharepoint/dsp">
      <version>string</version>
      <version>string</version>
    </versions>
  </soap:Header>
  <soap:Body>
    <queryRequest 
      xmlns="http://schemas.microsoft.com/sharepoint/dsp">
      <dsQuery        select="string" 
        resultContent="both or schemaOnly or dataOnly" 
        columnMapping="element or attribute" 
        resultNamespace="string" 
        resultPrefix="string" 
        resultRoot="string" 
        resultRow="string" 
        startPosition="string" 
        comparisonLocale="string">
        <Query          RowLimit="long">
          <ServerParameterInfo />
          <Fields>
            <Field 
              xsi:nil="true" />
            <Field xsi:nil="true" />
            <AllFields xsi:nil="true" />
          </Fields>
          <ServerParameters>
            <ServerParameter 
              xsi:nil="true" />
            <ServerParameter xsi:nil="true" />
          </ServerParameters>
          <Where>xml</Where>
          <OrderBy>
            <OrderField 
              xsi:nil="true" />
            <OrderField 
              xsi:nil="true" />
          </OrderBy>
        </Query>
      </dsQuery>
      <ptQuery>xml</ptQuery>
    </queryRequest>
  </soap:Body>
</soap:Envelope>

SOAP Response Format

The following example shows the syntax of a SOAP response returned through the data retrieval service. The placeholders shown must be replaced with actual values.

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <versions 
      xmlns="http://schemas.microsoft.com/sharepoint/dsp">
      <version>string</version>
      <version>string</version>
    </versions>
  </soap:Header>
  <soap:Body>
    <queryResponse 
      xmlns="http://schemas.microsoft.com/sharepoint/dsp">
      <xsd:schema>schema</xsd:schema>xml</queryResponse>
  </soap:Body>
</soap:Envelope>

See Also

Reference

StsAdapter Class
StsAdapter Members
List Data Retrieval Web Service