HTTP-Webdav
view release on metacpan or search on metacpan
sub callback
{
my ($userdata, $href, $results) = @_ ;
print "propfind callback userdata = $userdata href = $href\n" ;
$results -> iterate (\&iterator) ;
}
$sess -> simple_propfind ("/dav", NE_DEPTH_ONE, undef, \&callback) ;
print "Status: ", $sess -> get_error , "\n" ;
=head1 DESCRIPTION
This is the Perl interface to the neon HTTP and WebDAV client library.
Most of the documentation is automaticly generated from the C header
files of neon. So it looks a little bit C-ish, but is better than
nothing. See also the examples in the B<eg> directory.
If you not sure how it works consult the neon include files.
This document describes the function that are availabe. HTTP::Webdav::Constants
includes the constants defined by neon.
The neon API is encapsultated in a number of Perl classes. Everything that
doesn't fit in a class has gone to HTTP::Webdav::Util. (Maybe some of these
function will move to other classes in the future)
The clases are
=over 4
=item HTTP::Webdav
Main class which holds a http session
=item HTTP::Webdav::MultiStatus
Class to handle 207 responses
=item HTTP::Webdav::Hip
Interface to XML parser for properties
=item HTTP::Webdav::Lock
Holds a lock
=item HTTP::Webdav::LockSession
Holds a lock session
=item HTTP::Webdav::Propfind
Class to access the result of a PROPFIND
=item HTTP::Webdav::Propset
Class to acess properties of one resource
=item HTTP::Webdav::Request
Low level interface to http request
=item HTTP::Webdav::MD5
MD5 checksum
=item HTTP::Webdav::SSL
SSL support
=item HTTP::Webdav::Socket
Low level socket access
=back
WARNING: This wrapper is alpha code, while neon is around for some time and
stable to use, not all of the interface functions provided by this Perl module
has been tested extensivly, but most of them should work without problems (At least
they do it for me :-).
See in the eg directory for some examples.
=head1 CALLBACKS
Neon uses a lot off callbacks. Basicly there is no difference between using callbacks
in Perl and C. The only thing that is different, is that the functions that sets the
callbacks doesn't take the C<userdata> argument, which is used in C to pass a pointer
to the callback. Instead, the callback get the reference to the object that sets
the callback, pass as the userdata argument. This object is a hashreference and you
are free to store data in that hash. The only restriction is, that key starting
with two underscores ('__') are reserved for HTTP::Webdav internal use. Example:
sub datehdr
{
my ($userdata, $value) = @_ ;
$userdata -> {date} = $value ;
}
$sess = HTTP::Webdav -> new ;
$sess -> server ("www.ecos.de", 80) ;
$request = $sess -> request_create ("HEAD", "/") ;
# install callback which gets only Date header
$request -> add_response_header_handler ('Date', \&datehdr) ;
$request -> begin_request ;
$request -> end_request ;
print "Date: $request->{date}\n" ;
=head1 C-DATASTRUCTURS
=item uri
<string>
=item fd
<integer>
=item buffer
<string>
=back
=back
=head2 $propfind = $session -> propfind_create (uri,depth)
=over 4
=item Arguments
=over 4
=item $session
ne_session *
=item uri
<string>
=item depth
<integer>
=back
=back
=head2 int = $session -> propnames (href,depth,results)
Retrieve property names for the resources at 'href'. 'results'
callback is called for each resource. Use 'ne_propset_iterate' on
the passed results object to retrieve the list of property names.
=over 4
=item Arguments
=over 4
=item $session
ne_session *
=item href
<string>
=item depth
<integer>
=item Callback function: results
results (userdata,href,$propset)
Callback for handling the results of fetching properties for a
single resource (named by 'href'). The results are stored in the
result set 'results': use ne_propset_* to examine this object.
=over 4
=item userdata
void *
=item href
<string>
=item results
const ne_prop_result_set *
=back
=back
=back
=head2 int = $session -> proppatch (uri,items)
=over 4
=item Arguments
=over 4
=item $session
ne_session *
=item uri
<string>
=item items
const ne_proppatch_operation *
items = {
name => const ne_propname *, type => enum, value => <string>, };
=back
=head2 int = $session -> simple_propfind (uri,depth,props,results)
Fetch properties for a resource (if depth == NE_DEPTH_ZERO),
or a tree of resources (if depth == NE_DEPTH_ONE or _INFINITE).
Names of the properties required must be given in 'props',
or if props is NULL, *all* properties are fetched.
'results' is called for each resource in the response, userdata is
passed as the first argument to the callback. It is important to
note that the callback is called as the response is read off the
socket, so don't do anything silly in it (e.g. sleep(100), or call
any functions which use this session).
Note that if 'depth' is NE_DEPTH_INFINITY, some servers may refuse
the request.
Returns NE_*.
=over 4
=item Arguments
=over 4
=item $session
ne_session *
=item uri
<string>
=item depth
<integer>
=item props
const ne_propname *
props = {
nspace => <string>, name => <string>, };
=item Callback function: results
results (userdata,href,$propset)
Callback for handling the results of fetching properties for a
single resource (named by 'href'). The results are stored in the
result set 'results': use ne_propset_* to examine this object.
=over 4
=item userdata
void *
=item href
<string>
=item results
const ne_prop_result_set *
=back
=back
=back
=head2 int = $session -> simple_request ($request)
Dispatch a DAV request and handle a 207 error response appropriately
=over 4
=item Arguments
=over 4
=item $session
ne_session *
=item $request
ne_request *
=back
=back
=head2 int = $session -> unlock (lock)
Issue an UNLOCK request for the given lock
=back
=back
=back
=head1 Methods of HTTP::Webdav::Propfind
=head2 $propfind -> DESTROY ()
Destroy a propfind handler after use.
=over 4
=item Arguments
=over 4
=item $propfind
ne_propfind_handler *
=back
=back
=head2 int = $propfind -> allprop (result)
Find all properties.
Returns NE_*.
=over 4
=item Arguments
=over 4
=item $propfind
ne_propfind_handler *
=item Callback function: result
result (userdata,href,$propset)
Callback for handling the results of fetching properties for a
single resource (named by 'href'). The results are stored in the
result set 'results': use ne_propset_* to examine this object.
=over 4
=item userdata
void *
=item href
<string>
=item results
const ne_prop_result_set *
=back
=back
=back
=head2 void * = $propfind -> current_private ()
Retrieve the 'private' pointer for the current propset for the
given handler, as returned by the ne_props_create_complex callback
installed using 'ne_propfind_set_private'. If this callback was
not registered, this function will return NULL.
=over 4
=item Arguments
=over 4
=item $propfind
ne_propfind_handler *
=back
=back
=head2 $hip = $propfind -> get_parser ()
Return the XML parser for the given handler (only need if you want
to handle complex properties).
=over 4
=item Arguments
=over 4
=item $propfind
ne_propfind_handler *
=back
=back
=head2 $request = $propfind -> get_request ()
Return the request object for the given handler. You MUST NOT use
ne_set_request_body_* on this request object. (this call is only
needed if for instance, you want to add extra headers to the
PROPFIND request).
=over 4
=item Arguments
=over 4
=item $propfind
ne_propfind_handler *
=back
=back
=head2 int = $propfind -> named (prop,result)
Find properties named in a call to ne_propfind_set_flat and/or
ne_propfind_set_complex.
Returns NE_*.
=over 4
=item Arguments
=over 4
=item $propfind
ne_propfind_handler *
=item prop
const ne_propname *
prop = {
nspace => <string>, name => <string>, };
=item Callback function: result
result (userdata,href,$propset)
Callback for handling the results of fetching properties for a
single resource (named by 'href'). The results are stored in the
result set 'results': use ne_propset_* to examine this object.
=over 4
=item userdata
void *
=item href
<string>
=item results
const ne_prop_result_set *
=back
=back
=back
=head2 $propfind -> set_private (creator,userdata)
=over 4
=item Arguments
=over 4
=item $propfind
ne_propfind_handler *
=item creator
ne_props_create_complex
A "complex property" has a value which is structured XML. To handle
complex properties, you must set up and register an XML handler
which will understand the elements which make up such properties.
The handler must be registered with the parser returned by
'ne_propfind_get_parser'.
To store the parsed value of the property, a 'private' structure is
allocated in each propset (i.e. one per resource). When parsing the
property value elements, for each new resource encountered in the
response, the 'creator' callback is called to retrieve a 'private'
structure for this resource.
Whilst in XML element callbacks you will have registered to handle
complex properties, you can use the 'ne_propfind_current_private'
call to retrieve the pointer to this private structure.
To retrieve this 'private' structure from the propset in the
results callback, simply call 'ne_propset_private'.
=item userdata
void *
=back
=back
=head1 Methods of HTTP::Webdav::Propset
=head2 int = $propset -> iterate (iterator)
Iterate over all the properties in 'set', calling 'iterator'
for each, passing 'userdata' as the first argument to callback.
Returns:
whatever value iterator returns.
=over 4
=item Arguments
=over 4
=item $propset
const ne_prop_result_set *
The 'ne_simple_propfind' interface. ***
ne_simple_propfind allows you to fetch a set of properties for a
single resource, or a tree of resources. You set the operation
going by passing these arguments:
- the session which should be used.
- the URI and the depth of the operation (0, 1, infinite)
- the names of the properties which you want to fetch
- a results callback, and the userdata for the callback.
For each resource found, the results callback is called, passing
you two things along with the userdata you passed in originally:
- the URI of the resource (const char *href)
- the properties results set (const ne_prop_result_set *results)
=item Callback function: iterator
int = iterator (userdata,pname,value,status)
ne_propset_iterate iterates over a properties result set,
calling the callback for each property in the set. userdata is
passed as the first argument to the callback. value may be NULL,
indicating an error occurred fetching this property: look at
status for the error in that case.
If the iterator returns non-zero, ne_propset_iterate will return
immediately with that value.
=over 4
=item userdata
void *
=item pname
const ne_propname *
=item value
<string>
=item status
const ne_status *
=back
=back
=back
=head2 const char * = $propset -> lang (pname)
Return language string of property (may be NULL).
=over 4
=item Arguments
=over 4
=item $propset
const ne_prop_result_set *
The 'ne_simple_propfind' interface. ***
ne_simple_propfind allows you to fetch a set of properties for a
single resource, or a tree of resources. You set the operation
going by passing these arguments:
- the session which should be used.
- the URI and the depth of the operation (0, 1, infinite)
- the names of the properties which you want to fetch
- a results callback, and the userdata for the callback.
For each resource found, the results callback is called, passing
you two things along with the userdata you passed in originally:
- the URI of the resource (const char *href)
- the properties results set (const ne_prop_result_set *results)
=item pname
const ne_propname *
pname = {
nspace => <string>, name => <string>, };
=back
=back
=head2 void * = $propset -> private ()
Returns the private pointer for the given propset.
=over 4
=item Arguments
=over 4
=item $propset
const ne_prop_result_set *
The 'ne_simple_propfind' interface. ***
ne_simple_propfind allows you to fetch a set of properties for a
single resource, or a tree of resources. You set the operation
going by passing these arguments:
- the session which should be used.
- the URI and the depth of the operation (0, 1, infinite)
- the names of the properties which you want to fetch
- a results callback, and the userdata for the callback.
For each resource found, the results callback is called, passing
you two things along with the userdata you passed in originally:
- the URI of the resource (const char *href)
- the properties results set (const ne_prop_result_set *results)
=back
=back
=head2 const ne_status * = $propset -> status (propname)
Returns the status structure for fetching the given property on
this resource. This function will return NULL if the server did not
return the property (which is a server error).
=over 4
=item Arguments
=over 4
=item $propset
const ne_prop_result_set *
The 'ne_simple_propfind' interface. ***
ne_simple_propfind allows you to fetch a set of properties for a
single resource, or a tree of resources. You set the operation
going by passing these arguments:
- the session which should be used.
- the URI and the depth of the operation (0, 1, infinite)
- the names of the properties which you want to fetch
- a results callback, and the userdata for the callback.
For each resource found, the results callback is called, passing
you two things along with the userdata you passed in originally:
- the URI of the resource (const char *href)
- the properties results set (const ne_prop_result_set *results)
=item propname
const ne_propname *
propname = {
nspace => <string>, name => <string>, };
=back
=back
=head2 const char * = $propset -> value (propname)
Get the value of a given property. Will return NULL if there was an
error fetching this property on this resource. Call
ne_propset_result to get the response-status if so.
=over 4
=item Arguments
=over 4
=item $propset
const ne_prop_result_set *
The 'ne_simple_propfind' interface. ***
ne_simple_propfind allows you to fetch a set of properties for a
single resource, or a tree of resources. You set the operation
going by passing these arguments:
- the session which should be used.
- the URI and the depth of the operation (0, 1, infinite)
- the names of the properties which you want to fetch
- a results callback, and the userdata for the callback.
For each resource found, the results callback is called, passing
you two things along with the userdata you passed in originally:
- the URI of the resource (const char *href)
- the properties results set (const ne_prop_result_set *results)
=item propname
const ne_propname *
propname = {
nspace => <string>, name => <string>, };
=back
=back
=head1 Methods of HTTP::Webdav::Request
=head2 $request -> DESTROY ()
Destroy memory associated with request pointer
=over 4
=item Arguments
=over 4
=item $request
ne_request *
( run in 0.795 second using v1.01-cache-2.11-cpan-71847e10f99 )