WebDAV API - Documentation

Vocabulary

path

The path in our case is the REQUEST URI with first /webdav removed. So for /webdav/nodes/story/, path is /nodes/story/. For /webdav/nodes/story/1234/Content.html, path is /story/1234/Content.html.

route

A route is a convenient way of naming a path split into pieces. So the previous path as array("root", "nodes", "story", "1234", "Content.html") as route.

collection

A collection is the WebDAV term meaning "folder". A collection's URL always ends with /.

resource

A resource is a collection or a file.

member

A member is a collection item. Its a resource.

route handler

This is an internal thing. Every module can give (see hook_webdav_definitions) an association with a path and a callback function. Two modules can give different members for the same path. Si a route handler is :

1. array(
2.   'route'=>array('aaa','%bbb',...),       // route of the handler
3.   'module'=>'source_module_1',            // path owner
4.   'definitions' => array(
5.     array(
6.       'module'=>source_module_1_name,
7.       'members callback'=>...
8.       'arguments'=>....
9.     ),
10.     array(
11.       'module'=>source_module_2_name,
12.       'members callback'=>...
13.       'arguments'=>....
14.     ),
15.     ...
16.   )
17. )

So route handlers can be seen as an aggregation of hook_webdav_definitions invocation result.

resolved route handler

The same as route handler but with route replaced with the real route and with a new parameters member containing association key/values.

hook_webdav_definitions

Description

This hook enables modules to register webdav resource by their path.

1. function hook_webdav_definitions() {
2.   $items=array(
3.     '/node/%node_type/%node'=>array(
4.       'arguments'=>array(1,2),
5.       'members callback'=>'webdav_node_get_node_members',
6.       'put callback'=>'webdav_node_content_put',
7.       'access' => array (WEBDAV_NODE_PERMS_ACCESS),
8.     ),
9.   );
10.   return $items;
11. }

Path definition

A path can contain variable parts starting with %part_name. In this case, the system will search for a loader called $module_name.'_'.$part_name.'_load'. module_name is the name of the module which contains the hook. If loader is found, the loader result is used as argument value for part_name, else, the original matching path part is used as a string value.

if you use %%part_name, this will match the rest of the path from this point. As an example, when you have /my_collection/%%full_path matching /my_collection/aaa/bbb/ccc, you'll have full_path=>'aaa/bbb/ccc'. %% MUST BE UNIQUE AND AT THE END of the path. If the matching path don't have any "full path" (ex. /my_collection/), the result will be a / value.

As MENU API, every path should have a definition entry to be recognized. This is the case for collections but also for files. In most cases files are handled by a path like /aaa/bbb/ccc/%file_name.

WebDAV operation

Many operation can be done on a resource : populate members, get, put, delete, move, copy, etc... the definition block will contains callback function for each single operation that can be done on the define resource. So, there is no "hooks" for deleting, copying, getting, putting, etc. a webdav resource. Everything is done by callback as it is with Menu API. So, hook_webdav_definitions is actually the only real hook in this API.

webdav definition

Now let's go back to hook_webdav_definitions. As you know now, it returns an associative array of path and definition. A definition can have following properties :

• "module" : This is the module owner of this path. Every path got a owner in order to resolve conflicts. If not specified, the module owner is the module in which the path is declared. So if you want to attach resources to some path your module don't own, you just have to specify the module owner of it. In the future, system will detect conflicts over path when two modules claim to be owner of the same path.
• "{operation} callback" : Required if this is a collection resource. The function to call to populate members for this path.
• "arguments" : An array of arguments to pass to the any call back function. Each element is the identifier given with % or %%.
• "access" : An array of perms.

Webdav operation callbacks

A callback is linked to its definition, so every callback will have the same first parameters following arguments definition attribute. So if we have this definition :

1. '/node/%node_type/%node/%content_type'=>array(
2.   'arguments'=>array('node'),
3.   'members callback'=>'webdav_node_get_node_members',
4.   'get callback'=>'webdav_node_content_get',
5.   'access' => array (WEBDAV_NODE_PERMS_ACCESS),
6. ),  

The webdav_node_content_get callback will have $node as first parameter. This said, some callbacks can have more parameters. For example, for put, you'll have the $file_name containing the data to put.

get operation callback

This callback has only parameters defined in its webdav definition. The function can return a plain string or a file stream handler. If an error occurs, you have to user webdav_session_set_status with any HTTP error (ex. WEBDAV_HTTP_STATUS_FORBIDDEN).

1. function webdav_node_node_content_get($node) {
2.   return $node->body;
3. }

put operation callback

This callback have parameters defined in its webdav definition and a $file_name pointing to the file to put. If an error occurs, you have to user webdav_session_set_status with any HTTP error (ex. WEBDAV_HTTP_STATUS_FORBIDDEN).

1. function webdav_node_node_content_put($node, $file_name) {
2.   // as node_save don't do any check, we should validate permissions here
3.   if (!node_access("update", $node)) {
4.     error_log("==".$node->nid);
5.     webdav_session_set_status(WEBDAV_STATUS_FORBIDDEN);
6.     return;
7.   }
8.   $content = file_get_contents($file_name);
9.   $node->body = $content;
10.   _webdav_node_save($node);
11. }

create operation callback

This callback have parameters defined in its webdav definition and a $name for the new resource name to create. If an error occurs, you have to user webdav_session_set_status with any HTTP error (ex. WEBDAV_HTTP_STATUS_FORBIDDEN).

1. function webdav_node_node_create ($node_type, $name) {
2.   // Create the new node
3.   global $user;
4.   $node=(object)array();
5.   $node->title=$name;
6.   $node->body=webdav_node_create_node_default_body();
7.   $node->log=webdav_node_create_node_default_log_message();
8.   $node->type=$node_type;
9.   $node->uid=$user->uid;
10.   $node->status=0;
11.  
12.   if (!node_access( "create", $node)) {
13.     webdav_session_set_status(WEBDAV_STATUS_FORBIDDEN);
14.     return;
15.   }
16.   node_save($node);
17. }

delete operation callback

This callback has only the parameters defined in its webdav definition. If an error occurs, you have to user webdav_session_set_status with any HTTP error (ex. WEBDAV_HTTP_STATUS_FORBIDDEN).

1. function webdav_node_node_delete($node) {
2.   if (!node_access( "delete", $node)) {
3.     webdav_session_set_status(WEBDAV_STATUS_FORBIDDEN);
4.   } else {
5.     node_delete($node->nid);
6.   }
7. }

members operation callback

This callback has only the parameters defined in its webdav definition. It is used to get all members of a specified route. If an error occurs, you have to user webdav_session_set_status with any HTTP error (ex. WEBDAV_HTTP_STATUS_FORBIDDEN).

1. function webdav_node_node_members($node) {
2.   $format=$node->format;
3.   $extension = webdav_node_extension_for_input_format($format);
4.   $mime_type = webdav_node_mime_type_for_input_format($format);
5.  
6.   $items[] = array (
7.     'id' => "content.".$extension,
8.     'name' => $node->title.".".$extension,
9.     'created' => $node->created,
10.     'changed' => $node->changed,
11.     'size' => strlen($node->body),
12.     'type' => $mime_type,
13.     'encoding' => 'UTF8',
14.   );
15.   return $items;
16. }

copy operation callback

This callback is a bit more tricky. As it involves a source and a target, and each two of them go a path definition with arguments, the callback go first the target definition parameters as arguments, and after the source definition arguments.

Second tricky part, the callback should be attached somewhere. So it will be to the target path definition.

If an error occurs, you have to user webdav_session_set_status with any HTTP error (ex. WEBDAV_HTTP_STATUS_FORBIDDEN).

1. function webdav_node_webdav_copy(
2.   /* target path definition arguments */ $target_node_type,
3.   /* source path definition arguments */ $source_node) {
4.   if ($target_node_type!=$source_node->type) {
5.     webdav_session_set_status(WEBDAV_STATUS_FORBIDDEN);
6.     return;
7.   }
8.  
9.   // Create the new node
10.   global $user;
11.   $node=(object)array();
12.   $node->title=$name;
13.   $node->body=$source_node->body;
14.   $node->log=webdav_node_create_node_default_log_message();
15.   $node->type=$source_node->type;
16.   $node->uid=$user->uid;
17.   $node->status=0;
18.  
19.   // Check right
20.   if (!node_access( "create", $node)) {
21.     webdav_session_set_status(WEBDAV_STATUS_FORBIDDEN);
22.     return;
23.   }
24.   node_save($node);
25. }

copy operation callback

It's working quite the same as copy but with a $new_name between the two arguments definition.

1.   function webdav_node_move($target_node_type, $new_name, $source_node) {
2.   if ($target_node_type!=$source_node->type) {
3.     webdav_session_set_status(WEBDAV_STATUS_FORBIDDEN);
4.     return;
5.   }
6.  
7.   // as node_save don't do any check, we should validate permissions here
8.  if (!node_access( "update", $source_node)) {
9.    webdav_session_set_status(WEBDAV_STATUS_FORBIDDEN);
10.    return;
11.  }
12.  $source_node->title = $name;
13.  _webdav_node_save($source->parameters['node']);
14. }