Method Syntax

Each method topic includes a syntax section that describes the general form of the method call. For guidance on how to format a method in a post, see "Form of a POST command" later in this topic.

There are two ways to post commands using the remote procedure call (RPC) protocol of Microsoft Windows SharePoint Services. You can post single commands by embedding them in a URL, or you can use the batch functionality of Collaborative Application Markup Language (CAML) to send multiple requests per transaction.

Embedding a method in a URL

By embedding a request in a URL you can issue a method and the desired parameters to a server running Windows SharePoint Services. The syntax is as follows:

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

For more information, see URL Protocol.

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 used in the POST URL for all method requests to Windows SharePoint Services is as follows:

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

Note  When the request is not 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 requests in Windows SharePoint Services 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 following example, the Batch element 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>
  </Method>
  <Method ID="1,NewList">
    <SetVar Name="Cmd">NewList</SetVar>
    <SetVar Name="ListTemplate">100</SetVar>
    <SetVar Name="Title">Volunteers</SetVar>
  </Method>
</ows:Batch>

Syntax of a POST command for FrontPage Server Extensions from Microsoft

Each method is composed of the method name followed by a colon (:) and a space. Next comes the server_extension_version for FrontPage Server Extensions, and then the parameters for the method. 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 value of the parameter. For example:

&service_name=/fodo4

Parameter values use the following conventions:

For information about parameters, see the Parameters section of the reference page for the specific method.

Most POST commands in the RPC protocol for FrontPage Server Extensions 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 previous example, directory_name is the name of the root directory of the Web site, and program_name is the name of the program in FrontPage Server Extensions to which the POST command is addressed.

The date string is followed by HTTP header lines as illustrated in the next example:

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 client application responsible for the POST command, the length and type of POST command, as well as security information. Specifying the X-Vermeer-Content-Type header as in the example is required. Third-party developers who create applications that use RPC methods for interaction with Windows SharePoint Services must include this header in their POSTs. If the header is not included, the RPC operation will fail.

The last part of the POST command contains the method with any selected parameters and their values. For example:

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 FrontPage 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-urlencodedCRLF
CRLF
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.

Note  For more information about the POST command and HTTP headers, see the HTTP 1.0 specification on the World Wide Web Consortium Web page. This specification is used by the RPC protocol.

After the headers is a CRLF, followed by the RPC protocol method being sent to FrontPage 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 application sends a method to FrontPage Server Extensions by using a POST command, FrontPage Server Extensions sends back a standard HTTP OK to acknowledge receipt of the method. FrontPage Server Extensions responds to the method by sending an HTML encoded page to the client application. The following example shows a typical response:

Content-type: application/x-vermeer-rpc..X-FrontPage-User-Name:
usernameCRLF
CRLF
<html><head><title>vermeer.RPC
packet</title></head>LF<body>.
LF<p>method=list documents:
6.0.x.xxxxLF<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|author
LF<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|author
LF<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>

There are three possible variations for responses. First, the response is an HTML page that includes a only a message about the success of the method. Second, the response is an HTML page that includes only meta-information about the object of the method. Third, the response includes both a message and meta-information.

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

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