modules/dav/API.txt

// $Id$

This document is intended for developers who wish to utilize the DAV API or
troubleshoot the operation of DAV modules.

DATA TYPES
----------

  dav resource

    This is an array of two elements.


HOOKS API
---------
(This is yet to be written. For the time being, refer to file_server.module
as the canonical example of implementing the API provided by dav.module.)

  NAMESPACE QUERIES
  -----------------
    hook_dav_lookup()
    hook_dav_list()

  METADATA QUERIES
  ----------------
    hook_dav_propfind()

  READ-ONLY OPERATIONS
  --------------------
    hook_dav_get()

  MUTATIVE OPERATIONS
  -------------------
    hook_dav_put()
    hook_dav_mkcol()
    hook_dav_delete()

  NAMESPACE OPERATIONS
  --------------------
    hook_dav_rename()
    hook_dav_move()
    hook_dav_copy()

  LOCKING OPERATIONS
  ------------------
    hook_dav_lock()
    hook_dav_unlock()

GOTCHAS
-------
For DAV development work, you can't rely on the misguided-but-popular
tracing method of using var_dump() or print_r(), as any extraneous output
during the page request will simply be considered malformed input by the DAV
client. You also can't really test most of your code from the browser, as
DAV relies on a set of HTTP methods that your browser is unlikely to
support.

Instead, you should either write debugging output to the Drupal watchdog or
a file, use a real PHP debugger like those based on the open-source XDebug
extension, or perhaps try out the Trace module for Drupal.

DEBUGGING
---------
DAV problems can be difficult to troubleshoot. This section gives some
pointers on where to start.

If you're having troubles with a high-level GUI client (like the ones
included with Mac OS X or Windows), the first step is to shed some bloat and
uncertainty by trying out the cadaver command-line client as advised in
README.txt. Cadaver is simple enough that it should always work; if it
doesn't, you may have broken DAV at the application protocol level.

If so, you'll want to capture the HTTP traffic between your DAV client and
the Drupal server in order to troubleshoot. There are a great variety of
tools to accomplish this; in general, they are called packet sniffers or
protocol analyzers. Some popular ones include the GUI-based Wireshark
(formerly known as Ethereal) and the command-line tools tcpdump and tcpflow.
Depending on your setup, you can run these tools either on the server or on
your computer.

Here's an example of using tcpflow on Mac OS X (to adjust for your specific
situation, read the tcpflow manual page):

  # sudo tcpflow -c -i en0 -v port http

This will show you both the client request as well as the server response,
directly in your terminal window. (You'll also gain an undying appreciation
of the XML hell DAV is based on.)

On Mac OS X, the easiest way to install tcpflow is to use MacPorts. For most
Linux and *BSD distributions, tcpflow is available directly in the package
repository. On Windows, well, try Wireshark.
1	// $Id$
2
3	This document is intended for developers who wish to utilize the DAV API or
4	troubleshoot the operation of DAV modules.
5
6	DATA TYPES
7	----------
8
9	dav resource
10
11	This is an array of two elements.
12
13
14	HOOKS API
15	---------
16	(This is yet to be written. For the time being, refer to file_server.module
17	as the canonical example of implementing the API provided by dav.module.)
18
19	NAMESPACE QUERIES
20	-----------------
21	hook_dav_lookup()
22	hook_dav_list()
23
24	METADATA QUERIES
25	----------------
26	hook_dav_propfind()
27
28	READ-ONLY OPERATIONS
29	--------------------
30	hook_dav_get()
31
32	MUTATIVE OPERATIONS
33	-------------------
34	hook_dav_put()
35	hook_dav_mkcol()
36	hook_dav_delete()
37
38	NAMESPACE OPERATIONS
39	--------------------
40	hook_dav_rename()
41	hook_dav_move()
42	hook_dav_copy()
43
44	LOCKING OPERATIONS
45	------------------
46	hook_dav_lock()
47	hook_dav_unlock()
48
49	GOTCHAS
50	-------
51	For DAV development work, you can't rely on the misguided-but-popular
52	tracing method of using var_dump() or print_r(), as any extraneous output
53	during the page request will simply be considered malformed input by the DAV
54	client. You also can't really test most of your code from the browser, as
55	DAV relies on a set of HTTP methods that your browser is unlikely to
56	support.
57
58	Instead, you should either write debugging output to the Drupal watchdog or
59	a file, use a real PHP debugger like those based on the open-source XDebug
60	extension, or perhaps try out the Trace module for Drupal.
61
62	DEBUGGING
63	---------
64	DAV problems can be difficult to troubleshoot. This section gives some
65	pointers on where to start.
66
67	If you're having troubles with a high-level GUI client (like the ones
68	included with Mac OS X or Windows), the first step is to shed some bloat and
69	uncertainty by trying out the cadaver command-line client as advised in
70	README.txt. Cadaver is simple enough that it should always work; if it
71	doesn't, you may have broken DAV at the application protocol level.
72
73	If so, you'll want to capture the HTTP traffic between your DAV client and
74	the Drupal server in order to troubleshoot. There are a great variety of
75	tools to accomplish this; in general, they are called packet sniffers or
76	protocol analyzers. Some popular ones include the GUI-based Wireshark
77	(formerly known as Ethereal) and the command-line tools tcpdump and tcpflow.
78	Depending on your setup, you can run these tools either on the server or on
79	your computer.
80
81	Here's an example of using tcpflow on Mac OS X (to adjust for your specific
82	situation, read the tcpflow manual page):
83
84	# sudo tcpflow -c -i en0 -v port http
85
86	This will show you both the client request as well as the server response,
87	directly in your terminal window. (You'll also gain an undying appreciation
88	of the XML hell DAV is based on.)
89
90	On Mac OS X, the easiest way to install tcpflow is to use MacPorts. For most
91	Linux and *BSD distributions, tcpflow is available directly in the package
92	repository. On Windows, well, try Wireshark.