Method Syntax

Article
03/25/2009

Method Syntax

Each method page includes a Method Syntax section that describes the general form of the method call. For guidance on how to format a method to be sent over the wire, see Form of a POST Command.

Syntax for a SharePoint Team Services Post Command

There are two ways to POST SharePoint Team Services RPC protocol commands. You can post single methods and parameters by embedding them in a URL, or you can use the CAML language batch functionality to send multiple requests per transaction.

Embedding a Method in a URL

Embedding a request in a URL is a basic mechanism for issuing a method and the desired parameters to server running SharePoint Team Services. The syntax for using this mechanism is as follows:

http://[Web_name/]_vti_bin/owssvr.dll?Cmd=Method_name[&Parameter1=Value1&Parameter2=Value2...]

The following example creates a new custom list named "Employees" in a site called STSWeb1:

http://STSWeb1/_vti_bin/owssvr.dll?Cmd=NewList&ListTemplate=100&Title=Employees&LangID=1033

Using CAML batch functionality to send multiple requests

Issuing one command per POST requires many costly round trips to the server. To reduce the number of round trips, use the CAML Batch element to issue multiple commands per HTTP request. All requests must include a top-level DisplayPost command. The syntax for the POST URL for all SharePoint Team Services method requests is as follows:

POST /[Path/][Subweb/]_vti_bin/owssvr.dll?Cmd=DisplayPost

Note that when the request is not being issued through a proxy, you must post directly to the server-relative URL of the resource. The host name is not part of a server-relative URL.

The syntax for issuing multiple SharePoint Team Services requests is as follows:

POST /[Path/][Subweb/]_vti_bin/_vti_aut/owssvr.dll?Cmd=DisplayPost
<?xml version="1.0" encoding="UTF-8"?>
<ows:Batch OnError="Return">
  <Method ID="String">
    <SetVar Name="Cmd">Method1_name</SetVar>
    <SetVar Name="Parameter1">Value1</SetVar>
      .
      .
      .
    <SetVar Name="ParameterN">ValueN</SetVar>
  </Method>
  <Method ID="String">
    <SetVar Name="Cmd">Method2_name</SetVar>
    <SetVar Name="Parameter1">Value1</SetVar>
      .
      .
      .
    <SetVar Name="ParameterN">ValueN</SetVar>
  </Method>
      .
      .
      .
  <Method ID="String">
    <SetVar Name="Cmd">MethodN_name</SetVar>
    <SetVar Name="Parameter1">Value1</SetVar>
      .
      .
      .
    <SetVar Name="ParameterN">ValueN</SetVar>
  </Method>
</ows:Batch>

In the example below, the Batch method is used to create two custom lists named Meeting Topics and Volunteers.

POST /STSServer1/_vti_bin/_vti_aut/owssvr.dll?Cmd=DisplayPost

<?xml version="1.0" encoding="UTF-8"?>
<ows:Batch OnError="Return"> 
  <Method ID="0,NewList"> 
    <SetVar Name="Cmd">NewList</SetVar> 
    <SetVar Name="ListTemplate">100</SetVar> 
    <SetVar Name="Title">Meeting Topics</SetVar> 
    <SetVar Name="LangID">1033</SetVar> 
  </Method>
  <Method ID="1,NewList"> 
    <SetVar Name="Cmd">NewList</SetVar> 
    <SetVar Name="ListTemplate">100</SetVar> 
    <SetVar Name="Title">Volunteers</SetVar> 
    <SetVar Name="LangID">1033</SetVar> 
  </Method> 
</ows:Batch>

Syntax for a FrontPage Server Extensions POST command

Each method is made up of the method name followed by a colon (:) and a space. Next comes the server_extension_version, and then the method's parameters. Each parameter name has an ampersand (&) as its first character, and the parameter name is followed immediately by an equal sign (=) without spaces before it. The equal sign is immediately followed by the parameter's value. For example:

&service_name=/fodo4

Parameter values use the following conventions:

Font/Code	Meaning	Example
Italics	Variable	service_name
Angle brackets < >	Optional content	<platform=os>
Plain text	Literals	method
Disjunctive symbol \|	Separates equal alternative options	(true \| false)

For information about any particular parameter, see the Parameters section on the current method's Web page.

Most POST commands in the FrontPage Server Extensions RPC protocol take this form:

POST /directory_name/_vti_bin/_vti_aut/program_name.dll.
HTTP/1.0..Date:.Thu,.03.Dec.1998.19:09:16.GMT..

In the example above, directory_name is the name of the root directory of the web, and program_name is the name of the server extension program to which the POST is addressed.

The Date string is followed by HTTP header lines like these:

MIME-Version:.1.0..User-Agent:.client_name/version..
Host:.host_name..Accept:.auth/sicily..
Authorization:.Basic.cm9iZjpUS3NvKjUw.
Content-Length:.64..
Content-Type:.application/x-www-form-urlencoded..X-Vermeer-
Content-Type:.application/x-www-form-urlencoded....

These lines identify the server extension client responsible for the POST, the length and type of POST, as well as security information. The last part of the POST contains the method with any selected parameters and their values. For instance:

method=open+service%3a4%2e0%2e1%2e2207&service%5fname=%2fallnew.

Form of a POST Command

The first line of a POST command contains the POST command and the HTTP version in use. The POST command is followed by several HTTP headers, some of which are standard and some of which are unique to the server extensions. A typical POST command looks like this:

POST /allnew/_vti_bin/_vti_aut/author.dll HTTP/1.0CRLF
Date: Thu, 03 Dec 1998 19:09:16 GMTCRLF
MIME-Version: 1.0CRLF
User-Agent: MSFrontPage/4.0CRLF
Host: seattleCRLF
Accept: auth/sicilyCRLF
Authorization: Basic cm9iZjpUS3NvKjUwCRLF
Content-Length: 343CRLF
Content-Type: application/x-www-form-urlencodedCRLF
X-Vermeer-Content-Type: application/x-www-form-urlencodedCRLFCRLF
method=list+documents%3a4%2e0%2e1%2e2207&service%5fname=%2fallnew
&listHiddenDocs=false&listExplorerDocs=false&listRecurse=false&listFiles=true
&listFolders=true&listLinkInfo=true&listIncludeParent=true&listDerived=false
&listBorders=false&listChildWebs=true&initialUrl=&platform=WinI386
&folderList=%5b%3bTW%7c09+Nov+1998+17%3a03%3a25+%2d0000%5dLF

Each header line and the POST command line must end in a carriage-return/line feed (CRLF). Note that the CRLF is the byte sequence 0x0d, 0x0a, in accordance with the HTTP protocol. For more information about the POST command and HTTP headers, see the HTTP 1.0 specification on the World Wide Web Consortium web page http://www.w3.org/Protocols/rfc1945/rfc1945, which is used by the server extensions client server protocol (also known as the RPC protocol).

There is a CRLF after the headers, followed by the RPC protocol method being sent to the server extensions. Encode spaces in the method as the plus sign (+) character. Encode non-alphanumeric characters in the method using %XX encoding (for instance, the backslash is encoded as %5c). Add a line feed (LF) at the end of the method data.

Form of a Response to a POST Command

When a client sends a method to the server extensions via a POST command, the server extension send back a standard HTTP OK to acknowledge receipt of the method. Then the server extensions respond to the method by sending an HTML encoded page to the client. A typical response looks like this:

Content-type: application/x-vermeer-rpc..X-FrontPage-User-Name:
usernameCRLFCRLF
<html><head><title>vermeer.RPC 
packet</title></head>LF<body>.
LF<p>method=list documents: 
4.0.2.0000
LF<p>document_list=
LF<ul>
LF<ul>LF<li>document_name=Default.htm
LF<li>meta_info=
LF<ul>
LF<li>vti_author
LF<li>SR|authorLF<li>vti_title
LF<li>SW|Home Page
LF<li>vti_timecreated
LF<li>TR|10 Sep 1998 10:07:54 -0700
LF<li>vti_filesize
LF<li>IX|277
LF<li>vti_modifiedby
LF<li>SR|authorLF<li>vti_nexttolasttimemodified
LF<li>TR|10 Sep 1998 10:07:54 -0700
LF<li>vti_timelastmodified
LF<li>TR|10 Sep 1998 10:07:55 -0700
LF<li>vti_timelastwritten
LF<li>TX|10 Sep 1998 10:07:56 -0700
LF</ul>
LF</ul>
LF<ul>
LF<li>document_name=new1.htm
LF<li>meta_info=
LF<ul>
LF<li>vti_author
LF<li>SR|IUSR_author
. 
. 
.
</body>
</html>

In some cases, the response is an HTML page that includes a only a message about the success of the method. In other cases, the response is an HTML page that that includes only meta info about the object of the method. In still other cases, the response includes both a message and meta info.

In all cases, the response begins with a Content_type header. The HTML page that follows must have a line-feed (LF) in front of each of these HTML tags: <p>, <li>, <ul>, and </ul>.

For information about how responses are documented, see Return Values.

Share via

Method Syntax

Method Syntax

Syntax for a SharePoint Team Services Post Command

Embedding a Method in a URL

Using CAML batch functionality to send multiple requests

Syntax for a FrontPage Server Extensions POST command

Form of a POST Command

Form of a Response to a POST Command

Additional resources