HTTP::D...Resource(3)

📦
version 0.500.0 · 6 versions
, in opensuse-leap 16.0

Okay bestie, this is the HTTP::D...Resource(3) page — manual name folded in right here, no header-line copy-paste, we're doing this cute and correct. It's all about HTTP::DAV::Resource, and every tiny detail is staying. Periodt. 💅✨

👑 NAME 👑

HTTP::DAV::Resource — Represents and interfaces with WebDAV Resources. That's the whole name section and it ate. 🫶

✨ SYNOPSIS ✨

The synopsis is literally just:

Sample

Minimalist icon behavior. 🎀

🌸 DESCRIPTION 🌸

And the description is literally:

Description here

The placeholders are placeholding, bestie. 🫶

🛠️ CONSTRUCTORS 🛠️

new

Returns a new resource represented by the URI. Slay.

$r = HTTP::DAV::Resource->new(
        -uri => $uri,
        -LockedResourceList => $locks,
        -Comms => $comms
        -Client => $dav_client
     );

On creation a Resource object needs 2 other objects passed in:

  1. a "ResourceList" Object. This list will be added to if you lock this Resource.
  2. a "Comms" Object. This object will be used for HTTP communication.
  3. a "HTTP::DAV" Object. This object is where all locks are stored.
Not me noticing the original lists “2.” twice — I'm keeping it exactly as it appears. 💀

🌈 METHODS 🌈

get/GET

Performs an HTTP GET and returns a DAV::Response object.

$response = $resource->get;
print $resource->get_content if ($response->is_success);

put/PUT

Performs an HTTP PUT and returns a DAV::Response object.

$response = $resource->put( $string );

$string is be passed as the body.

e.g.

$response = $resource->put($string);
print $resource->get_content if ($response->is_success);

Will use a Lock header if this resource was previously locked.

copy

Not implemented. That's the whole thing. No extra lore. 🙈

move

Not implemented. Also no extra lore. 💀

delete

Performs an HTTP DELETE and returns a DAV::Response object.

$response = $resource->delete;
print "Delete successful" if ($response->is_success);

Will use a Lock header if this resource was previously locked.

options

Performs an HTTP OPTIONS and returns a DAV::Response object.

$response = $resource->options;
print "Yay for PUT!" if $resource->is_option("PUT");

mkcol

Performs a WebDAV MKCOL request and returns a DAV::Response object.

$response = $resource->mkcol;
print "MKCOL successful" if ($response->is_success);

Will use a Lock header if this resource was previously locked.

proppatch

The original says literally xxx. That's the entire description. Iconic, honestly. 💅

propfind

Performs a WebDAV PROPFIND request and returns a DAV::Response object.

$response = $resource->propfind;
if ($response->is_success) {
   print "PROPFIND successful\n";
   print $resource->get_property("displayname") . "\n";
}

A successful PROPFIND fills the object with much data about the Resource. Including:

displayname
...
TODO

lock

Performs a WebDAV LOCK request and returns a DAV::Response object.

$resource->lock(
        -owner   => "Patrick Collins",
        -depth   => "infinity"
        -scope   => "exclusive",
        -type    => "write"
        -timeout => TIMEOUT',
     )

lock takes the following arguments.

owner — Indicates who locked this resource.

The default value is:

DAV.pm/v$DAV::VERSION ($$)

e.g. DAV.pm/v0.1 (123)

If you use a URL as the owner, the module will automatically indicate to the server that is is a URL (<D:href>http://...</D:href>).

depth — Indicates the depth of the lock.

Legal values are 0 or infinity. (1 is not allowed).

The default value is infinity.

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.

scope — Indicates the scope of the lock.

Legal DAV values are "exclusive" or "shared".

The default value is exclusive.

See section 6.1 of RFC2518 for a description of shared vs. exclusive locks.

type — Indicates the type of lock (read, write, etc).

The only legal DAV value currently is "write".

The default value is write.

timeout — Indicates when the lock will timeout.

The timeout value may be one of, an Absolute Date, a Time Offset from now, or the word "infinity".

The default value is "infinity".

The following are all valid timeout values:

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

Absolute Date:

timeout at the indicated time & date (UTC/GMT)
   2000-02-31 00:40:33

timeout at the indicated date (UTC/GMT)
   2000-02-31

You can use any of the Absolute Date formats specified in HTTP::Date (see perldoc HTTP::Date).

Note: the DAV server may choose to ignore your specified timeout.

unlock

Performs a WebDAV UNLOCK request and returns a DAV::Response object.

$response = $resource->unlock()
$response = $resource->unlock( -force => 1 )
$response = $resource->unlock(
   -token => "opaquelocktoken:1342-21423-2323" )

This method will automatically use the correct locktoken If: header if this resource was previously locked.

force — Synonymous to calling $resource->forcefully_unlock_all.

forcefully_unlock_all

Remove all locks from a resource and return the last DAV::Response object. This method take no arguments.

$response = $resource->forcefully_unlock_all;

This method will perform a lockdiscovery against the resource to determine all of the current locks. Then it will UNLOCK them one by one. unlock( -token => locktoken ).

This unlock process is achievable because DAV does not enforce any security over locks.

Note: this method returns the LAST 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.
Don't run with this knife, you could hurt someone (or yourself).

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.

$response = $resource->steal_lock;

Synonymous to forcefully_unlock_all() and then lock().

lockdiscovery

Discover the locks held against this resource and return a DAV::Response object. This method take no arguments.

$response = $resource->lockdiscovery;
@locks = $resource->get_locks if $response->is_success;

This method is in fact a simplified version of propfind().

as_string

Returns a string representation of the object. Mainly useful for debugging purposes. It takes no arguments.

print $resource->as_string

🫶 ACCESSOR METHODS (get, set and is) 🫶

is_option

Returns a boolean indicating whether this resource supports the option passed in as a string. The option match is case insensitive so, PUT and Put should both work.

if ($resource->is_option( "PUT" ) ) {
   $resource->put( ... )
}
Note: this routine automatically calls the options() 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 options().

is_locked

Returns a boolean indicating whether this resource is locked.

@lock = $resource->is_locked( -owned=>[1|0] );

owned — this parameter is used to ask, is this resource locked by me?

Note: You must have already called propfind() or lockdiscovery()

e.g. Is the resource locked at all?

print "yes" if $resource->is_locked();

Is the resource locked by me?

print "yes" if $resource->is_locked( -owned=>1 );

Is the resource locked by someone other than me?

print "yes" if $resource->is_locked( -owned=>0 );

is_collection

Returns a boolean indicating whether this resource is a collection.

print "Directory" if ( $resource->is_collection );

You must first have performed a propfind.

get_uri

Returns the URI object for this resource.

print "URL is: " . $resource->get_uri()->as_string . "\n";

See the URI manpage from the LWP libraries (perldoc URI).

get_property

Returns a property value. Takes a string as an argument.

print $resource->get_property( "displayname" );

You must first have performed a propfind.

get_options

Returns an array of options allowed on this resource. Note: If $resource->options has not been called then it will return an empty array.

@options = $resource->get_options

get_content

Returns the resource's content/body as a string. The content is typically the result of a GET.

$content = $resource->get_content

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.

${$resource->get_content_ref} =~ s/\bfoo\b/bar/g;
Note: You must have already called get()

get_lock

Returns the DAV::Lock object if it exists. Requires opaquelocktoken passed as a parameter.

$lock = $resource->get_lock( "opaquelocktoken:234214--342-3444" );

get_locks

Returns a list of any DAV::Lock objects held against the resource.

@lock = $resource->get_locks( -owned=>[1|0] );

owned — this parameter indicates which locks you want.

  • '1', requests any of my locks. (Locked by this DAV instance).
  • '0' ,requests any locks not owned by us.
  • any other value or no value, requests ALL locks.
Note: You must have already called propfind() or lockdiscovery()

e.g. Give me my locks

@lock = $resource->get_locks( -owned=>1 );

Give me all locks

@lock = $resource->get_locks();

get_lockedresourcelist

Listed with no extra description in the original — just the name. 💅

get_parentresourcelist

Same deal: name only, no extra description. 🦋

get_comms

Name only, no extra description. 🎀

set_parent_resourcelist

$resource->set_parent_resourcelist( $resourcelist )

Sets the parent resource list (ask the question, which collection am I a member of?). See HTTP::DAV::ResourceList.

This page was brought to you by perl v5.42.0, dated 2024-10-17 — bye bestie, go lock some resources responsibly! 💖🔐✨

📦 where this page comes from