Section 10.4. Using URL Commands

10.4. Using URL Commands

URL commands get XML results from a SharePoint server through HTTP GET requests . You invoke the commands by specifying them as query strings in an address that has this form:

 http://  server  /  subsite  /_vti_bin/owssvr.dll?Cmd=  cmdname  &  param  =  value  &  param  =  value  ... 

URL commands don't alter the content database, so they don't require authentication. The RPC protocol provides a similar approach, but uses HTTP POST instead of GET, and so can include authentication information and thus change content. Table 10-6 lists the commands that can be invoked through HTTP GET.

The List and View parameters in Table 10-6 are specified as GUIDs. See the following section, "Getting GUIDs," for how to get those values from the list or view names . The URL commands also accept the set of optional parameters in Table 10-7 to modify the returned results.

Table 10-6. SharePoint URL commands

Command	Parameters	Use to
Dialogview	dialogview , location, FileDialogFilterValue	Open the view used in a dialog box for opening or saving files to a document library; or open the custom property form that is used when saving a file to a document library.
Display	List , XMLDATA	Run a database query against the list and return XML or HTML.
DisplayPost	PostBody , URLBase	Render the Collaborative Application Markup Language (CAML) assigned to the PostBody parameter.
ExportList	List	Export in CAML format the schema of the list.
GetProjSchema		Request the XML schema for a web site.
GetUsageBlob	BlobType	Get information about web site usage.
HitCounter	Page , Image , Custom, Digits	Render a hit counter in an img element on a page.
RenderView	List , View , URLBase	Request the contents of a view for the list.

Table 10-7. URL optional parameters

Parameter	Use to
FileDialogFilterValue	Set filters for a view, and to return the list of all files of a specified type from a document library according to filename extension (for example, *. doc , *. ppt , or *. xls ).
FilterField n	Specify the name of a field in the database, where n is an integer that is limited only by the number of fields allowed in the database table or by the length allowed for the URL field.
FilterValue n	Specify the string value on which to filter a field, where n is an integer that is limited only by the length allowed for the URL field.
SortField	Specify the name of the field on which to sort .
SortDir	Indicate an ascending (asc) or descending (desc) sort order.
Using	Specify a particular file containing CAML for the server to evaluate and render.

The HitCounter command is special. It renders an image used in an img element as shown here:

 <img src="../_vti_bin/owssvr.dll?Cmd=HitCounter&Page=TestPages/URLDemo.aspx&Image=4&Digits=3"> 

10.4.1. Getting GUIDs

The List and View parameters of the URL commands are the unique identifiers (GUIDs) SharePoint uses internally. There's no URL command to get a GUID from a name, so you have to use the SharePoint object model or a web service to get the values. The following sections demonstrate how to get the List and View GUIDs in these three different scenarios:

• Server .NET code in a web part using the SharePoint object model

• Remote .NET code using web services

• Remote VBA code using web services

The return values of all the procedures are the same, but as you will see from the code, how you get the results varies.

10.4.1.1 Using SharePoint objects

If you're working within SharePoint, you can get GUIDs through the SharePoint object model. The following procedures get a reference to the current web using the GetContextWeb shared method, then use that object to get the list or view by name from the Lists or Views collections. The ID property is a GUID, which must be converted to a string in order to be used from the URL command:

 ' Requires: Imports Microsoft.SharePoint.Webcontrols     Function GetListGuid(ByVal lName As String) As String         Try             ' Get the web from the current context.             Dim web As SPWeb = SPControl.GetContextWeb(context)             ' Get the list by name.             Dim lst As SPList = web.Lists(lName)             ' Get the GUID of the list.             Dim guid As System.Guid = lst.ID             ' Format the GUID as a string.             Return ("{" & guid.ToString & "}")         Catch ex As Exception             Debug.Write(ex.Message)             Return ""         End Try     End Function     Function GetViewGuid(ByVal lName As String, _       ByVal vName As String) As String         Try             ' Get the web from the current context.             Dim web As SPWeb = SPControl.GetContextWeb(context)             ' Get the view by name.             Dim view As SPView = web.Lists(lName).Views(vName)             ' Get the GUID of the list.             Dim guid As System.Guid = view.ID             ' Format the GUID as a string.             Return ("{" & guid.ToString & "}")         Catch ex As Exception             Debug.Write(ex.Message)             Return ""         End Try     End Function 

The error handling in these and subsequent procedures is very basic and simply returns "" if the list or view was not found. You may want to change that in your own code.

10.4.1.2 Using web services (.NET)

The Lists web service GetList method returns an XML description of the list, which contains an ID attribute with the list's GUID. You can use SelectSingleNode to extract the ID attribute from the XML, as shown here:

 ' Requires a Web reference to the Lists.asmx.     Function GetListGUID(ByVal lName As String) As String         Dim xn As Xml.XmlNode, lws As New Lists.Lists         Try             ' Get the XML result from the web service.             xn = lws.GetList(lName)             ' Get the GUID (it's the ID attribute of the root element).             Return xn.SelectSingleNode("//@ID").InnerText         Catch ex As Exception             Return ""         End Try     End Function 

The Views web service GetViewCollection returns an XML description listing the views available for a list. Each view has a Name attribute containing the GUID of the view. In order to extract that information, you need to find the view by its DisplayName attribute using an XPath expression in SelectSingleNode as follows :

 ' Requires a Web reference to the Views.asmx.     Function GetViewGUID(ByVal lName As String, ByVal vName As String) As String         Dim xn As Xml.XmlNode, vws As New Views.Views         Try             ' Get the XML result from the web service.             xn = vws.GetViewCollection(lName)             ' Get the GUID (it's the Name attribute)             ' where @DisplayName matches the view name.             Return xn.SelectSingleNode("//*[@DisplayName='" & _               vName & "']/@Name").InnerText         Catch ex As Exception             Return ""         End Try     End Function 

10.4.1.3 Using web services (VBA)

Getting the GUIDs from VBA is similar to using the web services from .NET; however, the XML objects and error handling are different than those available in .NET:

 ' Requires web reference to Lists.asmx.     Function GetListGUID(lName As String) As String         On Error Resume Next         Dim lws As New clsws_Lists         Dim xn As IXMLDOMNodeList, guid As String         ' Get the list.         Set xn = lws.wsm_GetList(lName)         ' Extract the GUID (it's the ID attribute).         guid = xn(0).selectSingleNode("//@ID").Text         ' Return "" if not found.         If Err Then guid = ""         ' Return the GUID.         GetListGUID = guid     End Function     ' Requires web reference to Views.asmx.     Function GetViewGUID(lName As String, vName As String) As String         On Error Resume Next         Dim vws As New clsws_Views         Dim xn As IXMLDOMNodeList, guid As String         ' Get the list's views.         Set xn = vws.wsm_GetViewCollection(lName)         ' Extract the GUID (it's the Name attribute).         guid = xn(0).selectSingleNode("//*[@DisplayName='" & _           vName & "']/@Name").Text         ' Return "" if not found.         If Err Then guid = ""         ' Return the GUID.         GetViewGUID = guid     End Function 

10.4.2. Executing URL Commands

You can use the URL commands as part of a link rendered on a page. For example, the following link displays the schema of a list:

 <a href="http://wombat1/_vti_bin/owssvr.dll?Cmd=ExportList&List={70F9FF01-15E5-4129-A370-9A31090204E9}">Show list schema</a> 

Or you can get the resulting XML in code using the .NET XML objects, as shown here:

 ' .NET: Use URL protocol to get a list's XML.     Function GetListSchema(ByVal lName As String) As String         Dim xdoc As New Xml.XmlDocument         Dim guid As String = GetListGUID(lName)         ' Create a reader for the URL.         Dim xr As New Xml.XmlTextReader("http://wombat1/_vti_bin/owssvr.dll" & _           "?Cmd=ExportList&List=" & guid)         ' Load the response.         xdoc.Load(xr)         ' Return the XML as a string.         Return xdoc.OuterXml     End Function 

Here's the same code in VBA:

 ' VBA: Use URL protocol to get a list's XML.     Function GetListSchema(ByVal lName As String) As String         Dim guid As String, xdoc As New DOMDocument         guid = GetListGUID(lName)         ' Load the response.         xdoc.Load ("http://wombat1/_vti_bin/owssvr.dll" & _           "?Cmd=ExportList&List=" & guid)         ' Return the XML as a string.         GetListXML xdoc.Text     End Function 

You can experiment with the URL commands to get the right combination of parameters. It is often easier to compose the command in the browser's address bar or as an HTML link before using it in code. For example, the first link below displays the visible list items in XML, whereas the second includes all of the hidden fields because it includes the parameter Query=* :

 <a href="http://wombat1/_vti_bin/owssvr.dll?Cmd=Display&List={70F9FF01-15E5-4129-A370-9A31090204E9}&XMLDATA=TRUE">Display list XML (minimal)</a><br>     <a href="http://wombat1/_vti_bin/owssvr.dll?Cmd=Display&List={70F9FF01-15E5-4129-A370-9A31090204E9}&XMLDATA=TRUE&  Query=*  ">Display list XML (full)</a> 

For complex queries, it is often easier to use web services or RPC.