.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DAV::Resource 3pm"
.TH DAV::Resource 3pm "2011-04-12" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTTP::DAV::Resource \- Represents and interfaces with WebDAV Resources
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Sample
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Description here
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.IP "\fBnew\fR" 4
.IX Item "new"
Returns a new resource represented by the \s-1URI\s0.
.Sp
\&\f(CW$r\fR = HTTP::DAV::Resource\->new( 
        \-uri => \f(CW$uri\fR, 
        \-LockedResourceList => \f(CW$locks\fR, 
        \-Comms => \f(CW$comms\fR 
        \-Client => \f(CW$dav_client\fR 
     );
.Sp
On creation a Resource object needs 2 other objects passed in:
.Sp
1. a \f(CW\*(C`ResourceList\*(C'\fR Object. This list will be added to if you lock this Resource.
.Sp
2. a \f(CW\*(C`Comms\*(C'\fR Object. This object will be used for \s-1HTTP\s0 communication.
.Sp
2. a \f(CW\*(C`HTTP::DAV\*(C'\fR Object. This object is where all locks are stored
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBget/GET\fR" 4
.IX Item "get/GET"
Performs an \s-1HTTP\s0 \s-1GET\s0 and returns a DAV::Response object.
.Sp
.Vb 2
\& $response = $resource\->get;
\& print $resource\->get_content if ($response\->is_success);
.Ve
.IP "\fBput/PUT\fR" 4
.IX Item "put/PUT"
Performs an \s-1HTTP\s0 \s-1PUT\s0 and returns a DAV::Response object.
.Sp
\&\f(CW$response\fR = \f(CW$resource\fR\->put( \f(CW$string\fR );
.Sp
\&\f(CW$string\fR is be passed as the body.
.Sp
.Vb 3
\& e.g.
\& $response = $resource\->put($string);
\& print $resource\->get_content if ($response\->is_success);
.Ve
.Sp
Will use a Lock header if this resource was previously locked.
.IP "\fBcopy\fR" 4
.IX Item "copy"
Not implemented
.IP "\fBmove\fR" 4
.IX Item "move"
Not implemented
.IP "\fBdelete\fR" 4
.IX Item "delete"
Performs an \s-1HTTP\s0 \s-1DELETE\s0 and returns a DAV::Response object.
.Sp
.Vb 2
\& $response = $resource\->delete;
\& print "Delete successful" if ($response\->is_success);
.Ve
.Sp
Will use a Lock header if this resource was previously locked.
.IP "\fBoptions\fR" 4
.IX Item "options"
Performs an \s-1HTTP\s0 \s-1OPTIONS\s0 and returns a DAV::Response object.
.Sp
.Vb 2
\& $response = $resource\->options;
\& print "Yay for PUT!" if $resource\->is_option("PUT");
.Ve
.IP "\fBmkcol\fR" 4
.IX Item "mkcol"
Performs a WebDAV \s-1MKCOL\s0 request and returns a DAV::Response object.
.Sp
.Vb 2
\& $response = $resource\->mkcol;
\& print "MKCOL successful" if ($response\->is_success);
.Ve
.Sp
Will use a Lock header if this resource was previously locked.
.IP "\fBproppatch\fR" 4
.IX Item "proppatch"
xxx
.IP "\fBpropfind\fR" 4
.IX Item "propfind"
Performs a WebDAV \s-1PROPFIND\s0 request and returns a DAV::Response object.
.Sp
.Vb 5
\& $response = $resource\->propfind;
\& if ($response\->is_success) {
\&    print "PROPFIND successful\en";
\&    print $resource\->get_property("displayname") . "\en";
\& }
.Ve
.Sp
A successful \s-1PROPFIND\s0 fills the object with much data about the Resource.  
Including:
   displayname
   ...
   \s-1TODO\s0
.IP "\fBlock\fR" 4
.IX Item "lock"
Performs a WebDAV \s-1LOCK\s0 request and returns a DAV::Response object.
.Sp
.Vb 7
\& $resource\->lock(
\&        \-owner   => "Patrick Collins",
\&        \-depth   => "infinity"
\&        \-scope   => "exclusive",
\&        \-type    => "write" 
\&        \-timeout => TIMEOUT\*(Aq,
\&     )
.Ve
.Sp
lock takes the following arguments.
.Sp
\&\fBowner\fR \- Indicates who locked this resource
.Sp
The default value is: 
 \s-1DAV\s0.pm/v$DAV::VERSION ($$)
.Sp
.Vb 1
\& e.g. DAV.pm/v0.1 (123)
.Ve
.Sp
If you use a \s-1URL\s0 as the owner, the module will
automatically indicate to the server that is is a 
\&\s-1URL\s0 (<D:href>http://...</D:href>)
.Sp
\&\fBdepth\fR \- Indicates the depth of the lock.
.Sp
Legal values are 0 or infinity. (1 is not allowed).
.Sp
The default value is infinity.
.Sp
A lock value of 0 on a collection will lock just the collection but not it's members, whereas a lock value of infinity will lock the collection and all of it's members.
.Sp
\&\fBscope\fR \- Indicates the scope of the lock.
.Sp
Legal \s-1DAV\s0 values are \*(L"exclusive\*(R" or \*(L"shared\*(R".
.Sp
The default value is exclusive.
.Sp
See section 6.1 of \s-1RFC2518\s0 for a description of shared vs. exclusive locks.
.Sp
\&\fBtype\fR \- Indicates the type of lock (read, write, etc)
.Sp
The only legal \s-1DAV\s0 value currently is \*(L"write\*(R".
.Sp
The default value is write.
.Sp
\&\fBtimeout\fR \- Indicates when the lock will timeout
.Sp
The timeout value may be one of, an Absolute Date, a Time Offset from now, or the word \*(L"infinity\*(R".
.Sp
The default value is \*(L"infinity\*(R".
.Sp
The following are all valid timeout values:
.Sp
Time Offset:
    30s          30 seconds from now
    10m          ten minutes from now
    1h           one hour from now
    1d           tomorrow
    3M           in three months
    10y          in ten years time
.Sp
Absolute Date:
.Sp
.Vb 2
\&    timeout at the indicated time & date (UTC/GMT)
\&       2000\-02\-31 00:40:33   
\&
\&    timeout at the indicated date (UTC/GMT)
\&       2000\-02\-31
.Ve
.Sp
You can use any of the Absolute Date formats specified in HTTP::Date (see perldoc HTTP::Date)
.Sp
Note: the \s-1DAV\s0 server may choose to ignore your specified timeout.
.IP "\fBunlock\fR" 4
.IX Item "unlock"
Performs a WebDAV \s-1UNLOCK\s0 request and returns a DAV::Response object.
.Sp
.Vb 4
\& $response = $resource\->unlock()
\& $response = $resource\->unlock( \-force => 1 )
\& $response = $resource\->unlock( 
\&    \-token => "opaquelocktoken:1342\-21423\-2323" )
.Ve
.Sp
This method will automatically use the correct locktoken If: header if this resource was previously locked.
.Sp
\&\fBforce\fR \- Synonymous to calling \f(CW$resource\fR\->forcefully_unlock_all.
.IP "\fBforcefully_unlock_all\fR" 4
.IX Item "forcefully_unlock_all"
Remove all locks from a resource and return the last DAV::Response object. This method take no arguments.
.Sp
\&\f(CW$response\fR = \f(CW$resource\fR\->forcefully_unlock_all;
.Sp
This method will perform a lockdiscovery against the resource to determine all of the current locks. Then it will \s-1UNLOCK\s0 them one by one. unlock( \-token => locktoken ).
.Sp
This unlock process is achievable because \s-1DAV\s0 does not enforce any security over locks.
.Sp
Note: this method returns the \s-1LAST\s0 unlock response (this is sufficient to indicate the success of the sequence of unlocks). If an unlock fails, it will bail and return that response.  For instance, In the event that there are 3 shared locks and the second unlock method fails, then you will get returned the unsuccessful second response. The 3rd unlock will not be attempted.
.Sp
Don't run with this knife, you could hurt someone (or yourself).
.IP "\fBsteal_lock\fR" 4
.IX Item "steal_lock"
Removes all locks from a resource, relocks it in your name and returns the DAV::Response object for the lock command. This method takes no arguments.
.Sp
\&\f(CW$response\fR = \f(CW$resource\fR\->steal_lock;
.Sp
Synonymous to \fIforcefully_unlock_all()\fR and then \fIlock()\fR.
.IP "\fBlockdiscovery\fR" 4
.IX Item "lockdiscovery"
Discover the locks held against this resource and return a DAV::Response object. This method take no arguments.
.Sp
.Vb 2
\& $response = $resource\->lockdiscovery;
\& @locks = $resource\->get_locks if $response\->is_success;
.Ve
.Sp
This method is in fact a simplified version of \fIpropfind()\fR.
.IP "\fBas_string\fR" 4
.IX Item "as_string"
Returns a string representation of the object. Mainly useful for debugging purposes. It takes no arguments.
.Sp
print \f(CW$resource\fR\->as_string
.SH "ACCESSOR METHODS (get, set and is)"
.IX Header "ACCESSOR METHODS (get, set and is)"
.IP "\fBis_option\fR" 4
.IX Item "is_option"
Returns a boolean indicating whether this resource supports the option passed in as a string. The option match is case insensitive so, \s-1PUT\s0 and Put are should both work.
.Sp
.Vb 3
\& if ($resource\->is_option( "PUT" ) ) {
\&    $resource\->put( ... ) 
\& }
.Ve
.Sp
Note: this routine automatically calls the \fIoptions()\fR routine which makes the request to the server. Subsequent calls to is_option will use the cached option list. To force a rerequest to the server call \fIoptions()\fR
.IP "\fBis_locked\fR" 4
.IX Item "is_locked"
Returns a boolean indicating whether this resource is locked.
.Sp
.Vb 1
\&  @lock = $resource\->is_locked( \-owned=>[1|0] );
.Ve
.Sp
\&\fBowned\fR \- this parameter is used to ask, is this resource locked by me?
.Sp
Note: You must have already called \fIpropfind()\fR or \fIlockdiscovery()\fR
.Sp
e.g. 
Is the resource locked at all?
 print \*(L"yes\*(R" if \f(CW$resource\fR\->\fIis_locked()\fR;
.Sp
Is the resource locked by me?
 print \*(L"yes\*(R" if \f(CW$resource\fR\->is_locked( \-owned=>1 );
.Sp
Is the resource locked by someone other than me?
 print \*(L"yes\*(R" if \f(CW$resource\fR\->is_locked( \-owned=>0 );
.IP "\fBis_collection\fR" 4
.IX Item "is_collection"
Returns a boolean indicating whether this resource is a collection.
.Sp
.Vb 1
\& print "Directory" if ( $resource\->is_collection );
.Ve
.Sp
You must first have performed a propfind.
.IP "\fBget_uri\fR" 4
.IX Item "get_uri"
Returns the \s-1URI\s0 object for this resource.
.Sp
.Vb 1
\& print "URL is: " . $resource\->get_uri()\->as_string . "\en";
.Ve
.Sp
See the \s-1URI\s0 manpage from the \s-1LWP\s0 libraries (perldoc \s-1URI\s0)
.IP "\fBget_property\fR" 4
.IX Item "get_property"
Returns a property value. Takes a string as an argument.
.Sp
.Vb 1
\& print $resource\->get_property( "displayname" );
.Ve
.Sp
You must first have performed a propfind.
.IP "\fBget_options\fR" 4
.IX Item "get_options"
Returns an array of options allowed on this resource.
Note: If \f(CW$resource\fR\->options has not been called then it will return an empty array.
.Sp
\&\f(CW@options\fR = \f(CW$resource\fR\->get_options
.IP "\fBget_content\fR" 4
.IX Item "get_content"
Returns the resource's content/body as a string.
The content is typically the result of a \s-1GET\s0.
.Sp
\&\f(CW$content\fR = \f(CW$resource\fR\->get_content
.IP "\fBget_content_ref\fR" 4
.IX Item "get_content_ref"
Returns the resource's content/body as a reference to a string.
This is useful and more efficient if the content is large.
.Sp
${$resource\->get_content_ref} =~ s/\ebfoo\eb/bar/g;
.Sp
Note: You must have already called \fIget()\fR
.IP "\fBget_lock\fR" 4
.IX Item "get_lock"
Returns the DAV::Lock object if it exists. Requires opaquelocktoken passed as a parameter.
.Sp
.Vb 1
\& $lock = $resource\->get_lock( "opaquelocktoken:234214\-\-342\-3444" );
.Ve
.IP "\fBget_locks\fR" 4
.IX Item "get_locks"
Returns a list of any DAV::Lock objects held against the resource.
.Sp
.Vb 1
\&  @lock = $resource\->get_locks( \-owned=>[1|0] );
.Ve
.Sp
\&\fBowned\fR \- this parameter indicates which locks you want.
 \- '1', requests any of my locks. (Locked by this \s-1DAV\s0 instance).
 \- '0' ,requests any locks not owned by us.
 \- any other value or no value, requests \s-1ALL\s0 locks.
.Sp
Note: You must have already called \fIpropfind()\fR or \fIlockdiscovery()\fR
.Sp
e.g. 
 Give me my locks
  \f(CW@lock\fR = \f(CW$resource\fR\->get_locks( \-owned=>1 );
.Sp
.Vb 2
\& Give me all locks
\&  @lock = $resource\->get_locks();
.Ve
.IP "\fBget_lockedresourcelist\fR" 4
.IX Item "get_lockedresourcelist"
.PD 0
.IP "\fBget_parentresourcelist\fR" 4
.IX Item "get_parentresourcelist"
.IP "\fBget_comms\fR" 4
.IX Item "get_comms"
.IP "\fBset_parent_resourcelist\fR" 4
.IX Item "set_parent_resourcelist"
.PD
\&\f(CW$resource\fR\->set_parent_resourcelist( \f(CW$resourcelist\fR )
.Sp
Sets the parent resource list (ask the question, which collection am I a member of?). See HTTP::DAV::ResourceList.