Last modified: March 23, 2010
Applies to: SharePoint Foundation 2010
In this article
Embedding a Method in a URL
Using CAML Batch Functionality to Send Multiple Requests
Syntax of a POST Command for FrontPage Server Extensions from Microsoft
Form of a POST Command
Form of a Response to a POST Command
Each of the following method topics includes a syntax section that describes the general form of the method call. For guidance about 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 SharePoint Foundation. 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.
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 DisplayPostcommand. The syntax used in the POST URL for all method requests to SharePoint Foundation is as follows:
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 SharePoint Foundation 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>
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:
Parameter values use the following conventions:
Angle brackets (< >)
Disjunctive symbol (|)
Separates equal alternative options
(true | false)
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 SharePoint Foundation 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:
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.
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 that is 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.
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 only a message about the success or failure 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.