.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "Net::DAV::LockManager 3"
.TH Net::DAV::LockManager 3 "2016-08-24" "perl v5.16.3" "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"
Net::DAV::LockManager \- Provides support for WebDAV locking
.SH "VERSION"
.IX Header "VERSION"
This document describes Net::DAV::LockManager version 1.304.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Net::DAV::LockManager;
\&
\&    my $mgr = Net::DAV::LockManager\->new();
\&    if ( my $lock = $mgr\->lock({ \*(Aqpath\*(Aq => \*(Aq/foo/bar\*(Aq, \*(Aqowner\*(Aq => \*(Aqfred\*(Aq }) ) {
\&        # Fred has access.
\&        # Fred changes file.
\&        $mgr\->unlock({
\&            \*(Aqpath\*(Aq => \*(Aq/foo/bar\*(Aq, \*(Aqowner\*(Aq => \*(Aqfred\*(Aq, \*(Aqtoken\*(Aq => $lock\->{\*(Aqtoken\*(Aq}
\&        });
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Net::DAV::LockManager\*(C'\fR class provides the ability to handle resource locking
in the style needed by WebDAV. It does not perform OS-level locking, but only
locking in the mind of the LockManager.
.PP
The current implementation only supports exlusive locking. However, it does
support indirect locks and expiration of locks. It also maintains the lock
tokens and manages ownership independent of OS-level ownership.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "\fInew()\fP"
.IX Subsection "new()"
Create a new \f(CW\*(C`Net::DAV::LockManager\*(C'\fR object to manage locking.
.ie n .SS "can_modify( $hashref )"
.el .SS "can_modify( \f(CW$hashref\fP )"
.IX Subsection "can_modify( $hashref )"
Return true if the path supplied in the hash ref can be modified by the user
specified in the hash ref. The hash ref supplies the following named parameters.
.IP "path" 4
.IX Item "path"
Required parameter specifying the path as a string.
.IP "owner" 4
.IX Item "owner"
Required parameter specifying the user that wishes to modify the resource.
.IP "token" 4
.IX Item "token"
Optional parameter specifying the token returned when the resource (or an
ancestor) was locked. This parameter may be either a single token as a string
or an array reference containing token strings.
.ie n .SS "lock( $hash_ref )"
.el .SS "lock( \f(CW$hash_ref\fP )"
.IX Subsection "lock( $hash_ref )"
Lock the path supplied in the hash ref based on the parameters in the hash
ref.
.IP "path" 4
.IX Item "path"
Required parameter specifying the path as a string.
.IP "owner" 4
.IX Item "owner"
Required parameter specifying the user that wishes to lock the resource.
.IP "timeout" 4
.IX Item "timeout"
Optional parameter specifying a number of seconds in the future to expire the
lock. This is considered a request and the the actual timeout may be different.
.Sp
If not supplied, a default timeout of 15 minutes is used.
.IP "depth" 4
.IX Item "depth"
Optional parameter specifying the depth the locking effect. As per the WebDAV
specification \s-1RFC 4918,\s0 two values are accepted \fI0\fR and \fIinfinity\fR. A value
of \fI0\fR applies only to the specified resource. The depth of \fIinfinity\fR
applies to a collection and all of its descendants.
.Sp
The default value of this parameter is \fIinfinity\fR.
.IP "scope" 4
.IX Item "scope"
Optional parameter specifying the scope of the lock. The WebDAV specification
supports two values: \fIexclusive\fR and \fIshared\fR. The \f(CW\*(C`LockManager\*(C'\fR only
supports \fIexplusive\fR at this time.
.Sp
The default value is \fIexclusive\fR.
.IP "token" 4
.IX Item "token"
Optional parameter specifying the token returned when an ancestor of the the
specified resource was locked. This parameter may be either a single token as
a string or an array reference containing token strings.
.PP
Returns a \f(CW\*(C`Net::DAV::Lock\*(C'\fR object describing the lock on success and \f(CW\*(C`undef\*(C'\fR
on failure.
.ie n .SS "refresh_lock( $hash_ref )"
.el .SS "refresh_lock( \f(CW$hash_ref\fP )"
.IX Subsection "refresh_lock( $hash_ref )"
Updates the timeout value on the lock specified by the supplied hash ref. The
hash ref contains the following named parameters.
.IP "path" 4
.IX Item "path"
Required parameter specifying the path as a string.
.IP "owner" 4
.IX Item "owner"
Required parameter specifying the user that wishes to lock the resource. This
name must match the owner of the lock.
.IP "token" 4
.IX Item "token"
Required parameter specifying the token returned when the resource (or an
ancestor) was locked. This parameter may be either a single token as a string
or an array reference containing token strings.
.IP "timeout" 4
.IX Item "timeout"
Optional parameter specifying a number of seconds in the future to expire the
lock. This is considered a request and the the actual timeout may be different.
.Sp
If not supplied, a default timeout of 15 minutes is used.
.PP
Returns a \f(CW\*(C`Net::DAV::Lock\*(C'\fR object describing the lock on success and \f(CW\*(C`undef\*(C'\fR
on failure.
.ie n .SS "unlock( $hash_ref )"
.el .SS "unlock( \f(CW$hash_ref\fP )"
.IX Subsection "unlock( $hash_ref )"
Unlock the resource specified by the hash ref. The hash ref specifies the 
resource to unlock and the credentials needed to access it. The named
parameters in the hash are
.IP "path" 4
.IX Item "path"
Required parameter specifying the path as a string.
.IP "owner" 4
.IX Item "owner"
Required parameter specifying the user that wishes to lock the resource. This
name must match the owner of the lock.
.IP "token" 4
.IX Item "token"
Required parameter specifying the token returned when the resource was locked.
This parameter may be either a single token as a string or an array reference
containing token strings.
.PP
Returns true on success, false otherwise.
.ie n .SS "find_lock( $hash_ref )"
.el .SS "find_lock( \f(CW$hash_ref\fP )"
.IX Subsection "find_lock( $hash_ref )"
Find the lock that pretects the resource listed in \f(CW$hash_ref\fR. Returns the
\&\f(CW\*(C`Net::DAV::Lock\*(C'\fR object representing the lock, or \f(CW\*(C`undef\*(C'\fR if none is found.
.PP
The hash reference contains the path to the resource that we want to check.
.IP "path" 4
.IX Item "path"
Required parameter specifying the path as a string.
.ie n .SS "list_all_locks( $hash_ref )"
.el .SS "list_all_locks( \f(CW$hash_ref\fP )"
.IX Subsection "list_all_locks( $hash_ref )"
List all the locks that pretect the resource listed in \f(CW$hash_ref\fR. Returns an
array of \f(CW\*(C`Net::DAV::Lock\*(C'\fR objects representing the locks.
.PP
The hash reference contains the path to the resource that we want to check.
.IP "path" 4
.IX Item "path"
Required parameter specifying the path as a string.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
Most of the methods perform parameter validation and \f(CW\*(C`die\*(C'\fR on error. This is
based on the idea that this is a mostly internal module that should be being
called from non-user code. Therefore, it is the client code's responsibility
to get the parameters right.
.ie n .IP """Parameter should be a hash reference.""" 4
.el .IP "\f(CWParameter should be a hash reference.\fR" 4
.IX Item "Parameter should be a hash reference."
All methods of this class take a hash reference to support named and optional
parameters.
.ie n .IP """Missing required \*(Aq%s\*(Aq parameter.""" 4
.el .IP "\f(CWMissing required \*(Aq%s\*(Aq parameter.\fR" 4
.IX Item "Missing required %s parameter."
The specified parameter was required but not supplied,
.ie n .IP """Not a clean path""" 4
.el .IP "\f(CWNot a clean path\fR" 4
.IX Item "Not a clean path"
\&\f(CW\*(C`LockManager\*(C'\fR only supports absolute paths that have no \f(CW\*(C`..\*(C'\fR or \f(CW\*(C`.\*(C'\fR segments
and do not end in \f(CW\*(C`/\*(C'\fR.
.ie n .IP """Not a valid owner name.""" 4
.el .IP "\f(CWNot a valid owner name.\fR" 4
.IX Item "Not a valid owner name."
The specified user name does not look like a username.
.ie n .IP """\*(Aq%s\*(Aq is not a supported value for scope.""" 4
.el .IP "\f(CW\*(Aq%s\*(Aq is not a supported value for scope.\fR" 4
.IX Item "%s is not a supported value for scope."
At present, \f(CW\*(C`LockManager\*(C'\fR only supports the \fIexclusive\fR scope for locking.
.ie n .IP """\*(Aq%s\*(Aq is not a supported value for depth.""" 4
.el .IP "\f(CW\*(Aq%s\*(Aq is not a supported value for depth.\fR" 4
.IX Item "%s is not a supported value for depth."
According to \s-1RFC 4918,\s0 the only supported depth values are \fI0\fR and \fIinfinity\fR.
.ie n .IP """\*(Aq%s\*(Aq is not a supported value for timeout.""" 4
.el .IP "\f(CW\*(Aq%s\*(Aq is not a supported value for timeout.\fR" 4
.IX Item "%s is not a supported value for timeout."
Only integer timeout values are supported.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
ModName requires no configuration files or environment variables.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
None.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.SH "AUTHOR"
.IX Header "AUTHOR"
G. Wade Johnson  \f(CW\*(C`wade@cpanel.net\*(C'\fR
Erin Schoenhals  \f(CW\*(C`erin@cpanel.net\*(C'\fR
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2010, cPanel, Inc. All rights reserved.
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.