Prerequisites
This document assumes the reader has knowledge and experience working with WebDAV standard
If you do not have the knowledge please consult the following documents :
Standard WebDAV
Ghost CFS is WebDAV class 1 compliant and thus locking is not supported by our CFS servers and APIs
WebDAV URLs
For any CFS user the main entry point WebDAV URL is of the following format
{protocol}://{server}/vcweb/dav/users/{user}/files/GDrv/{user}/
where :
{protocol} is either http or https {server} is the server public IP address or DNS name {user} is the CFS user account name (username)
So an example WebDAV url for a user called "adam" would be
http://somehostname.com/vcweb/dav/users/adam/files/GDrv/adam/
A word regarding https
You can use https with WebDAV if you have configured ghost CFS with an authentic SSL certificate signed by one of the verified SSL providers, otherwise your browser will show you a certificate error screen, and your standard WebDAV client / WebDAV library might not work.
Special Reserved URLs
Some WebDAV URLs are reserved , those are URLs for resources of special purpose
Recycle Bin URL
Each user has a recycle bin URL associated with the recycle bin resource, this resource is not visible to you if you query the WebDAV entry point URL for a user.
The Recycle bin URL for a user is
{protocol}://{server}/vcweb/dav/users/{user}/files/GDrv/{user}/RecycleBin/
The recycle bin has some special semantics :
- A PROPFIND request to the recycle bin would list all content of the recycle bin
- A Move request to a resource in the recycle bin with a Destination which is outside of the recycle bin results in a Restore of the softly deleted item.
- A Move request to a resource outside the recycle bin with the recycle bin as a destination is a SOFT Delete request
- A Delete request to a resource in the recycle bin would result in a hard delete , you can no longer restore this resource.
Templates URLs
There are a number of document templates which are available with Ghost CFS, those are useful for integration with online editors.
These templates are public and available for any user to copy them :
Template URL format
{protocol}://{server}/vcweb/dav/users/public/files/GDrv/public/templates/{templateName}
Where template names are :
| Excel97Document.xls |
|
| HyperTextMarkupLanguage.html |
|
| New CommaSeparatedValues.csv |
|
| New newTextDocument.txt |
|
| New OpenDocumentSpreadsheet.ods |
|
| New Powerpoint97Document.ppt |
|
| New Powerpoint97SlideShow.pps |
|
| OpenDocumentPresentation.odp |
|
| OpenDocumentText.odt |
|
| OpenOfficeDocument.sxw |
|
| OpenOfficePresentation.sxi |
|
| OpenOfficeSpreadsheet.sxc |
|
| RichTextFormat.rtf |
|
| Word2007Document.docx |
|
| Word97Document.doc |
|
Using a template file
To copy a template to a user directory For example My Documents of a user "Max" issue a standard WebDAV copy request
COPY
http://server.com/vcweb/dav/users/public/files/GDrv/public/templates/Word97Document.doc
Destination : http://server.com/vcweb/dav/users/max/files/GDrv/max/My%20Documents/NewWordFile.doc
Standard WebDAV supported methods
WebDAV Lite (Browser Friendly)
Since normal WebDAV involves special HTTP methods (verbs) , setting request headers, and returns new response codes, some clients (including browsers) might have difficulties using standard WebDAV for such clients we provide WebDAV lite , with a number of workarounds for browsers and HTTP only clients.
Session Cookie authentication
Ghost CFS standard webdav supports digest authentication. However for Ghost Lite cookie authentication is supported with CFS session cookies ,
for information on how to obtain a Ghost CFS session cookie check the RESTful API documentation.
Ghost CFS WebDAV apis renew the session cookie if it is getting near to its expiration period whenever the user makes a new request however if the user is idle and no request is being generated the session cookie is likely to expire.
If the session cookie expired Ghost CFS WebDAV apis will return Unauthorized 401 responses and the developer should call the session API again to renew the session cookie.
Method tunneling
Ghost CFS allows WebDAV method tunneling through the use of webdav "method" parameter. This allows simple clients not supporting webdav to perform webdav operations :
Using WebDAV method tunneling developers can use a GET wherever the request does not have a body and a POST when the request has one.
PROPFIND :
For Propfind GET or POST can be used , with a GET and since there is no response body a Propfind All Prop request is assumed
GET /vcweb/dav/users/skattan/files/GDrv/skattan/?method=propfind
If you are submitting a body with your propfind response use a POST instead.
COPY, MOVE, DELETE, PROPPATCH
The same arguments apply for COPY, MOVE, PROPPATCH, and DELETE requests where GET and POST can be removed along with the "method" parameter
However to remain adherent to REST specifications it is recommended that you use a POST for DELETE, PROPPATCH, and MOVE methods , since those change the representation and the internal state of the resource being moved or deleted, therefore a POST is recommended.
For a COPY POST and GET can be used.
Passing Headers as Parameters
Since WebDAV standard involves setting some request headers (including Depth header in case of PROPFIND requests and Destination header in the case of COPY and MOVE requests) and since not all environments (such as flash) support setting HTTP request headers, Ghost CFS allows such headers to be sent as parameters instead of headers.
Therefore in case of a PROPFIND request to Joe's My Pictures folder one would send the following request
GET http://server.com/vcweb/dav/users/joe/files/GDrv/joe/My%20Pictures/?method=PROPFIND&Depth=2
In the case of a MOVE request to rename one of joe's pictures from "Picture1.jpg" to "New Picture.jpg" the request would be :
GET http://server.com/vcweb/dav/users/joe/files/GDrv/joe/My%20Pictures/Picture1.jpg?method=MOVE&
Destionation=http%3A%2F%2Fserver.com%2Fvcweb%2Fdav%2Fusers%2Fjoe%2Ffiles%2FGDrv%2Fjoe%2FMy%2520Pictures%2FNew%20Picture.jpg
Or following the REST guidelines where a MOVE should actually use a POST
POST http://server.com/vcweb/dav/users/joe/files/GDrv/joe/My%20Pictures/Picture1.jpg
PARAMETERS
method=MOVE
Destionation=http%3A%2F%2Fserver.com%2Fvcweb%2Fdav%2Fusers%2Fjoe%2Ffiles%2FGDrv%2Fjoe%2FMy%2520Pictures%2FNew%20Picture.jpg
Notice that the Destination URL is encoded using the standard URL Encoding which is what the HTTP standard specifies when sending GET parameters which are not URL safe.
Wrapped XML responses
Besides standard HTTP status codes returned WebDAV standard specifies a number of additional status codes,browsers and non standard webdav clients might not know how to behave when receiving those response codes, also sometimes the browser's default behavior cannot be overridden if a certain response code is received.
An example of this is when receiving the response code 401 (Unauthorized) when sending an Ajax request, in this case the browser will always intercept the call and open the default authentication prompt dialog box, however as a developer you would like to use session cookie authentication instead of standard WebDAV authentication, thus you would not want the browser to handle authentication but you would like to handle this in your code.
The solution is sending a certain request parameter telling CFS WebDAV APIs to wrap responses in XML, where WebDAV status codes as well as response body bytes are returned in the XML , and only 200 OK http status code is sent in the status header.
The parameter is called GHOST
If you specify GHOST=XML as a parameter , the response returned is in the following format :
<GhostWebDAV>
<Status Code="{WebDAV status code}" Message="{WebDAV Status message}" />
<Body> {Original response body} </Body>
</GhostWebDAV>
Where WebDAV status code is the original WebDAV status code that should be returned in header in case you did not send the wrapping parameter. WebDAV status text is the original status text that should be in header.
Original response body is the response body appended as an XML element.
Example PROPFIND with a wrapped response
Request : GET http://server.com/vcweb/dav/users/someone/files/GDrv/someone?method=PROPFIND&Depth=0&GHOST=XML
Response:
Response Code : 200
Response Text : OK
Response body :
<?xml version="1.0" encoding="utf-8" ?>
<GhostWebDAV>
<Status Message="Multi-Status" Code="207" />
<Body>
<D:multistatus xmlns:D="DAV:">
<D:response xmlns:D="DAV:">
<D:href xmlns:D="DAV:">http://g.ho.st/vcweb/dav/users/someone/files/GDrv/someone/</D:href>
<D:propstat xmlns:D="DAV:">
<D:prop xmlns:D="DAV:">
<D:displayname xmlns:D="DAV:">someone</D:displayname>
<D:getcontentlanguage xmlns:D="DAV:">English</D:getcontentlanguage>
<D:getcontentlength xmlns:D="DAV:">924329934</D:getcontentlength>
<D:getcontenttype xmlns:D="DAV:"></D:getcontenttype>
<D:resourcetype xmlns:D="DAV:"><D:collection xmlns:D="DAV:"/></D:resourcetype>
</D:prop>
<D:status xmlns:D="DAV:">HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
</Body>
</GhostWebDAV>
Another value for GHOST parameter is data
If you set the parameter GHOST=DATA the response returned is in the following format :
<GhostWebDAV>
<Status Code="{WebDAV status code}" Message="{WebDAV Status message}" />
<Body>
<![CDATA[
{ Special encoded response body}
]]>
</Body>
</GhostWebDAV>
{ Special encoded response body} is the original webDAV response however it is encoded.
Response encoding depends on the requested resource content type : If the resource is a plain text document , the result is a UTF-8 string which represents the response body
Otherwise the response is a Base64 encoded version of the resource content.
Additional Parameters
When dealing with files resources and using the browser the behavior is sometimes indeterministic and depends on the browser itself , for example a browser sometimes will open the file resource and display its content in the browser window, at other times it might call a Third party plugin to handle the file (examples include PDFs and word files). For other content types the browsers usually display the download dialog box.
For the developer to control whether a file is opened inline ( in the browser window or its content made available to the caller ) or opened as an attachment (browser pops the download dialog) the developer should specify the disposition parameter.
disposition=in : the requested resource should be explicitly opened in the browser window
disposition=at : the requested resource should force the browser to popup the download dialog.
Examples :
Opening a file inline in a browser.
http://server.com/vcweb/dav/users/sharky/files/GDrv/sharky/30_70Logo.jpg?disposition=in
Downloading a file as an attachment.
http://server.com/vcweb/dav/users/sharky/files/GDrv/sharky/30_70Logo.jpg?disposition=at
