Sooner or later, every SharePoint developer will start a project with the requirement of accessing documents in SharePoint remotely. You will have the brilliant idea of using the SharePoint web services to upload files but after some research you realise there is no web service for uploading or downloading documents, just checking in or out. Did the SharePoint team forgotten to put a web service in? Not really. A large number of people have created a web service that uses the SharePoint object model to upload files. But there is really no need in doing so since there are 2 protocols you can use:

  • WebDAV: Web-based Distributed Authoring and Versioning, an extension to the HTTP protocol that allows clients to perform remote web content authoring operations.
  • FrontPage RPC: FrontPage Remote Procedure Calls, again, an extension to the HTTP protocol that allows clients to perform remote web content authoring operations on SharePoint web applications or web sites extended with the FrontPage Server Extensions.

I am not going to cover WebDAV here but if you like more info, have a look at RFC 2518. So what exactly are FrontPage RPCs? They first appeared with FrontPage Server Extensions as a way for remotely publishing your web sites. They utilise the HTTP protocol to access and modify web site content using text commands – officially called FrontPage RPC methods. WSS still includes the API and all you need to have installed is WSS. There is no requirement to install FrontPage Server Extensions in addition to SharePoint. I know people are put off by the name and the fact that it isn’t that popular but let me try and convince you by telling you who implements the FrontPage RPCs at present. Well, they are used by the Microsoft Office Suite including version 12 (2007). SharePoint Designer (which is FrontPage v12 really) relies heavily on FrontPage RPCs and WSS RPCs – another similar protocol – to modify SharePoint content. Microsoft Word uses the RPCs to access documents in SharePoint too.

The protocol is implemented as HTTP requests and responses. A request will need to have specific headers: "Content-type: application/x-vermeer-rpc" and "X-Vermeer-Content-Type: application/x-www-form-urlencoded". The request method must be "POST" and the method to execute is passed as plain text in the request’s body. You will also need to authenticate yourself – usually NTLM authentication will be required depending on your SharePoint authentication settings. When a method is acknowledged, a standard HTTP OK will be send back. The result of the method is send to the client through an HTTP response in HTML format.

You can use Fiddler to capture and display all HTTP traffic so that you can have a better understanding of what is going on with the implementation. There is a .NET issue though that closes the connection to the web server when using Fiddler with your .NET app. There is a workaround though, as I was informed by Eric Lawrence; In Fiddler, click Rules > Customize Rules. Scroll down to the bottom of the OnBeforeResponse method and uncomment the code block at the very bottom of the function. It doesn’t matter what version of .NET Framework you use and there are no requirements for any additional references besides what you already have in your standard project. You will need to work with the System.Net.HttpWebRequest and System.Net.HttpWebResponse classes for this one so it will be a good idea to import the System.Net namespace. All FrontPage RPC methods have to be sent in an identical way:

HttpWebRequest _fpRequest = HttpWebRequest)WebRequest.Create("http://spwebapp/spsite/_vti_bin/_vti_aut/author.dll");

_fpRequest.UserAgent = "FrontPage RPC Client X";

_fpRequest.Method = "POST";

_fpRequest.ContentType = "application/x-www-form-urlencoded";

_fpRequest.Headers.Add("X-Vermeer-Content-Type", "application/x-www-form-urlencoded");                

_fpRequest.Credentials = CredentialCache.DefaultCredentials;

The very first line of code shows where the request should be made against. Lets consider the scenario where you have a document in a document library at the SharePoint site http://webapp/sites/projectsite. The file could be at http://webapp/sites/projectsite/doclib/doc1.docx. That means that your request will need to be send made against http://webapp/sites/projectsite/_vti_bin/_vti_aut/athor.dll, just as the _layouts folder works. The second line assigns a UserAgent ID to the request. You dont really need to do that so go ahead and skip it entirely if you like. The 3rd line specified that the request method is going to be POST, while the 4th and 5th line add content type headers to the request. Since we will need to authenticate against WSS, we send our default Windows credentials if they are applicable. The final peace of the puzzle is the method text itself. You specify what method to execute with the following text:

Method=<method name>:<protocol version>&service_name&<method specific parameters>

For example: method=get+document:6.0.n.nnnn&service_name=/&document_name=file_name&old_theme_html=false&force=true&get_option=none&doc_version=&timeout=0

The method above requests the file with file name "file_name" in the web site "/". There are other parameters but usually they are specific to each method. You do not have to specify the protocol version at all nor the service_name. Keep in mind though that if no service_name is specified, the root site is opened ("/"). These are some of the methods you can use:

Name

Description

add document to source control

Adds a file to a source control database.

 

 

 

 

checkin document

Returns a file to source control.

checkout document

Enables the user currently authenticated to make changes to a document under source control.

create url-directory

Creates a folder for the current Web site, but only used for backward compatibility.

get document

Retrieves the specified document for viewing on the client computer.

list versions

Retrieves metadata for all the versions of the specified document.

move document

Changes the name of the selected document to the new name provided by the user.

put document

Writes a file to a directory in an existing Web site.

put documents

Writes files to a directory in an existing Web site.

remove documents

Deletes the specified documents or folders from the Web site specified by the service_name parameter.

uncheckout document

Undoes a check-out of a file from a source control database.

url to web url

Given a URL for a file, returns the URL of the Web site to which the file belongs, and the subsite, if applicable.

 

 

 

The most interesting of all is the "url to web url" method. You are going to need this for all the methods simply because you can’t distinguish the SharePoint site and document library in your full url that easy. Let’s consider http://server/part/part/part/doc1.doc. Which part of the url is the site, which is the document library and which is simply a folder? By passing the full url to the "url to web url" method, we are requesting that information. You will receive two values in return called weburl and fileurl. The weburl value will be the SharePoint site (web) url on the server. So for example if you had a site at http://webapp/site1/chidsite, that will return /site1/childsite. If you had http://webapp/site1, that will return simply "/". The fileurl will be the file location relative to the web site. So if the document is stored in the document library called "Documents", you will get a value of /Documents/file.ext. FrontPage RPCs don’t really care about document libraries or not, they can publish files anywhere and that is why they treat the document library as just another folder. They do take into account though the document library behaviour so if document versioning is enabled and you try to overwrite an already checked in document then your operation will fail prompting you to check out the file first. Same thing applies for security; if you haven’t got access to a file then you can’t retrieve it or modify it in any way.

So the method string for undoing a check out for a document will be: method=uncheckout+document&service_name=weburl&document_name=fileurl&force=false&rlsshortterm=false. Notice the use of the weburl and fileurl retrieved by "url to web url" method. All return values will be as HTML pages so you will need to process those to retrieve the end result.

For a full list of methods you can use, have a look at FrontPage Server Extensions RPC Protocol or get your copy of the WSS SDK. For a .NET Implementation, you can use the project at GotDotNet.

Advertisements