Davix::DavFile Class Reference

Davix File Interface. More...

`#include <davfile.hpp>`

## Data Structures

class | Iterator

## Public Member Functions

| DavFile (Context &c, const Uri &url)
| default constructor
| DavFile (Context &c, const RequestParams &params, const Uri &url)
| DavFile (const DavFile &orig)
virtual | ~DavFile ()
| destructor
const Uri & | getUri () const
| return Uri of the current file
std::vector< DavFile > | getReplicas (const RequestParams *params, DavixError **err) throw ()
| return all replicas associated to this file
dav_ssize_t | readPartialBufferVec (const RequestParams *params, const DavIOVecInput *input_vec, DavIOVecOuput *ioutput_vec, const dav_size_t count_vec, DavixError **err) throw ()
| Vector read operation Able to do several read on several data chunk in one single operation. Uses Http multi-part when supported by the server, simulate a vector read operation otherwise.
dav_ssize_t | readPartial (const RequestParams *params, void *buff, dav_size_t count, dav_off_t offset, DavixError **err) throw ()
| Partial position independant read.
dav_ssize_t | getToFd (const RequestParams *params, int fd, DavixError **err) throw ()
| Get the full file content and write it to file descriptor.
dav_ssize_t | getToFd (const RequestParams *params, int fd, dav_size_t size_read, DavixError **err) throw ()
| Get the first 'size_read' bytes of the file and write it to file descriptor.
dav_ssize_t | getFull (const RequestParams *params, std::vector< char > &buffer, DavixError **err) throw ()
| Get the full file content in a dynamically allocated buffer.
dav_ssize_t | get (const RequestParams *params, std::vector< char > &buffer)
| Get the full file content to buffer.
void | put (const RequestParams *params, int fd, dav_size_t size_write)
| Create/Replace file content.
void | put (const RequestParams *params, const char *buffer, dav_size_t size_write)
| Create/Replace file content.
void | move (const RequestParams *params, DavFile &destination)
| move
void | deletion (const RequestParams *params=NULL)
| Suppress the current entity or collection.
int | deletion (const RequestParams *params, DavixError **err) throw ()
| Suppress the current entity or collection.
void | makeCollection (const RequestParams *params=NULL)
| create a collection (directory or bucket) at the current url
int | makeCollection (const RequestParams *params, DavixError **err) throw ()
| create a collection (directory or bucket) at the current url
StatInfo & | statInfo (const RequestParams *params, StatInfo &info)
| execute a file meta-data query
int | stat (const RequestParams *params, struct stat *st, DavixError **err) throw ()
| execute a POSIX-like stat() query
Iterator | listCollection (const RequestParams *params)
| Collection listing.
std::string & | checksum (const RequestParams *params, std::string &checksm, const std::string &chk_algo)
| compute checksum of the file
int | checksum (const RequestParams *params, std::string &checksm, const std::string &chk_algo, DavixError **err) throw ()
| compute checksum of the file with the given algorithm (MD5, CRC32, ADLER32)
void | prefetchInfo (off_t offset, dav_size_t size_read, advise_t adv)
| provide information on the next file operation
QuotaInfo & | quotaInfo (const RequestParams *params, QuotaInfo &info)
| retrieve quota information
| DEPRECATED (dav_ssize_t getAllReplicas(const RequestParams *params, ReplicaVec &vec, DavixError **err))
| DEPRECATED (int putFromFd(const RequestParams *params, int fd, dav_size_t size_write, DavixError **err) throw())

## Detailed Description

Davix File Interface.

Davix File interface

## Constructor & Destructor Documentation

## DavFile()

Davix::DavFile::DavFile | ( | Context & | c,
|  | const Uri & | url )

default constructor

Parameters

  c | context
  url | remote file URL

References DavFile().

Referenced by DavFile(), and move().

## Member Function Documentation

## checksum() [1/2]

std::string & Davix::DavFile::checksum | ( | const RequestParams * | params,
|  | std::string & | checksm,
|  | const std::string & | chk_algo )

compute checksum of the file

with the given algorithm (MD5, CRC32, ADLER32)

server implementation dependend

Davix::checksum support LCGDM-DAV, dCache Jetty and Aws S3 checksum support

Parameters

  params | request parameters
  checksm | checksum buffer
  chk_algo | string of the algorithm (eg: "MD5" )

Returns
  reference to checksm

Exceptions

  throw | DavixException if error occurs

Context c;
DavFile file(c, Uri(http://example.org/file_to_checksum));
std::string chk;
// calculate MD5, also supports CRC32, ADLER32
file.checksum(NULL, chk, “MD5”);
std::cout << “MD5 ” << chk << std::endl;

## checksum() [2/2]

int Davix::DavFile::checksum | ( | const RequestParams * | params,
|  | std::string & | checksm,
|  | const std::string & | chk_algo,
|  | DavixError ** | err )
throw | ( | ) |  |  |

compute checksum of the file with the given algorithm (MD5, CRC32, ADLER32)

Exception safe version of checksum

Context c;
DavixError* err = NULL;
DavFile file(c, Uri(http://example.org/file_to_checksum));
std::string chk;
// calculate MD5, also supports CRC32, ADLER32
file.checksum(NULL, chk, “MD5”, &err);
std::cout << “MD5 ” << chk << std::endl;

## deletion() [1/2]

int Davix::DavFile::deletion | ( | const RequestParams * | params,
|  | DavixError ** | err )
throw | ( | ) |  |  |

Suppress the current entity or collection.

Exception safe version of deletion(const RequestParams* params = NULL)

Context c;
DavixError* err = NULL;
// to delete a WebDAV collection
DavFile myDavCollection(c, Uri(“davs://example.org/collection_to_delete”));
myDavCollection.deletion(NULL, &err);
// to delete a S3 bucket (note: bucket has to be empty or operation will fail)
// setup S3 authorisation keys
RequestParams params;
params.setAwsAuthorizationKeys(“xxxxx”, “yyyyy”);
DavFile myS3Bucket(c, Uri(“s3://bucket_to_delete.example.org”));
myS3Bucket.deletion(&params, &err);

## deletion() [2/2]

void Davix::DavFile::deletion | ( | const RequestParams * | params = NULL | ) |

Suppress the current entity or collection.

Parameters

  params | Davix request Parameters

Exceptions

  throw | DavixException if error occurs

Context c;
// to delete a WebDAV collection
DavFile myDavCollection(c, Uri(“davs://example.org/collection_to_delete”));
myDavCollection.deletion(NULL);
// to delete a S3 bucket (note: bucket has to be empty or operation will fail)
// setup S3 authorisation keys
RequestParams params;
params.setAwsAuthorizationKeys(“xxxxx”, “yyyyy”);
DavFile myS3Bucket(c, Uri(“s3://bucket_to_delete.example.org”));
myS3Bucket.deletion(&params);

## DEPRECATED() [1/2]

Davix::DavFile::DEPRECATED | ( | dav_ssize_t | getAllReplicasconst RequestParams *params, ReplicaVec &vec, DavixError **err | ) |

Deprecated
  deprecated, will be removed in 2.0

## DEPRECATED() [2/2]

Davix::DavFile::DEPRECATED | ( | int | putFromFdconst RequestParams *params, int fd, dav_size_t size_write, DavixError **err) throw( | ) |

Deprecated
  please use put() as the replacement, will be removed in 2.0

## get()

dav_ssize_t Davix::DavFile::get | ( | const RequestParams * | params,
|  | std::vector< char > & | buffer )

Get the full file content to buffer.

Parameters

  params | Davix request Parameters
  buffer | reference to a vector for storing the result

Returns
  total number of bytes read, or -1 if error occures

Get the file content in a dynamically allocated buffer

WARNING: this operation is without size limit for the content

Context c;
DavixError* err = NULL;
DavFile file(c, Uri(“http://example.org/file_to_download”));
std::vector<char> buffer;
// warning, this operation has no size limit regarding the content
file.get(NULL, buffer);
// do things with buffer
// ...

## getFull()

dav_ssize_t Davix::DavFile::getFull | ( | const RequestParams * | params,
|  | std::vector< char > & | buffer,
|  | DavixError ** | err )
throw | ( | ) |  |  |

Get the full file content in a dynamically allocated buffer.

Parameters

  params | Davix request Parameters
  buffer | reference to a vector for the result
  err | Davix error report

Returns
  total number of bytes read, or -1 if error occures

Context c;
DavixError* err = NULL;
DavFile file(c, Uri(“http://example.org/file_to_download”));
std::vector<char> buffer;
// warning, this operation has no size limit regarding the content
file.getFull(NULL, buffer, &err);
// do things with buffer
// ...

## getReplicas()

std::vector< DavFile > Davix::DavFile::getReplicas | ( | const RequestParams * | params,
|  | DavixError ** | err )
throw | ( | ) |  |  |

return all replicas associated to this file

Replicas are found using a corresponding The MetaLink standard ( rfc5854, rfc6249 )

Parameters

  params | Davix Request parameters
  err | Davix error report

Returns
  Replica vector, if error is found return empty vector and set err properly

Context c;
DavixError* err = NULL;
DavFile file(c, Uri("http://example.org/dir1/file1"));
std::vector<DavFile> resultVec;
resultVec = file.getReplicas(NULL, &err);

## getToFd() [1/2]

dav_ssize_t Davix::DavFile::getToFd | ( | const RequestParams * | params,
|  | int | fd,
|  | dav_size_t | size_read,
|  | DavixError ** | err )
throw | ( | ) |  |  |

Get the first 'size_read' bytes of the file and write it to file descriptor.

Parameters

  params | Davix request Parameters
  fd | file descriptor for write operation
  size_read | number of bytes to read
  err | Davix error report

Returns
  total number of bytes read, or -1 if error occures

Context c;
DavixError* err = NULL;
DavFile file(c, Uri("http://example.org/dir1/file_to_download"));
int fd = open(“/tmp/local_file” O_WRONLY, O_CREAT);
// get 200 bytes from file
file.getToFd(NULL, fd, 200, &err);

## getToFd() [2/2]

dav_ssize_t Davix::DavFile::getToFd | ( | const RequestParams * | params,
|  | int | fd,
|  | DavixError ** | err )
throw | ( | ) |  |  |

Get the full file content and write it to file descriptor.

Parameters

  params | Davix request Parameters
  fd | file descriptor for write operation
  err | Davix error report

Returns
  total number of bytes read, or -1 if error occures

Context c;
DavixError* err = NULL;
DavFile file(c, Uri("http://example.org/dir1/file_to_download"));
int fd = open(“/tmp/local_file” O_WRONLY, O_CREAT);
// get full file
file.getToFd(NULL, fd, &err);

## listCollection()

Iterator Davix::DavFile::listCollection | ( | const RequestParams * | params | ) |

Collection listing.

Parameters

  params | Davix request parameters

Returns
  Iterator to the collection

Contect c;
DavFile file(c, Uri(“http://example.org/collection_to_list”));
DavFile::Iterator it = file.listCollection(NULL);
// prints out entries' name
do{
std::cout << it.name() << std::endl;
}while(it.next());

## makeCollection() [1/2]

int Davix::DavFile::makeCollection | ( | const RequestParams * | params,
|  | DavixError ** | err )
throw | ( | ) |  |  |

create a collection (directory or bucket) at the current url

Exception safe version of makeCollection(const RequestParams *params = NULL)

Context c;
DavixError* err = NULL;
// Instantiate RequestParams object to hold request options
RequestParams params;
// to create a WebDav collection
DavFile myDavCollection(c, Uri(“dav://example.org/collection_to_create”));
myDavCollection.makeCollection(NULL, &err);
// to create a new S3 bucket
// first we need to setup S3 authorisation keys for this request
params.setAwsAuthorizationKeys(“xxxxx”, “yyyyy”);
DavFile myS3Bucket(c, Uri(“s3://bucket_to_create.example.org”));
myS3Bucket.makeCollection(&params, &err);

## makeCollection() [2/2]

void Davix::DavFile::makeCollection | ( | const RequestParams * | params = NULL | ) |

create a collection (directory or bucket) at the current url

Parameters

  params | Davix request Parameters

Exceptions

  throw | DavixException if error occurs

Context c;
DavixError* err = NULL;
// Instantiate RequestParams object to hold request options
RequestParams params;
// to create a WebDav collection
DavFile myDavCollection(c, Uri(“dav://example.org/collection_to_create”));
myDavCollection.makeCollection(NULL);
// to create a new S3 bucket
// first we need to setup S3 authorisation keys for this request
params.setAwsAuthorizationKeys(“xxxxx”, “yyyyy”);
DavFile myS3Bucket(c, Uri(“s3://bucket_to_create.example.org”));
myS3Bucket.makeCollection(&params);

## move()

void Davix::DavFile::move | ( | const RequestParams * | params,
|  | DavFile & | destination )

move

Parameters

  params | Davix request Parameters
  destination | destination resource

Move the current resource to Destination.

The result of the operation depend of the protocol used.

Protocol supported currently: WebDav, S3

Context c;
DavFile source(c, Uri(“http://example.org/old_location”));
DavFile destination(c, Uri(“http://example.org/new_location”));
source.move(NULL, destination);

References DavFile().

## prefetchInfo()

void Davix::DavFile::prefetchInfo | ( | off_t | offset,
|  | dav_size_t | size_read,
|  | advise_t | adv )

provide information on the next file operation

provide information on the next file operations for optimizations and prefetching

Parameters

  offset |
  size_read |
  adv |

## put() [1/2]

void Davix::DavFile::put | ( | const RequestParams * | params,
|  | const char * | buffer,
|  | dav_size_t | size_write )

Create/Replace file content.

Parameters

  params | Davix request Parameters
  buffer | buffer with data to write
  size_write | number of bytes to write

Exceptions

  throw | DavixException if an error occurs

Set a new content for the file. The new content comes from buffer.

Context c;
DavFile file(c, Uri(“http://example.org/file_to_create”));
char buffer[255];
// fills buffer with something useful
// execute put
file.put(NULL, &buffer, static_cast<dav_size_t>sizeof(buffer));

References put().

## put() [2/2]

void Davix::DavFile::put | ( | const RequestParams * | params,
|  | int | fd,
|  | dav_size_t | size_write )

Create/Replace file content.

Parameters

  params | Davix request Parameters
  fd | file descriptor
  size_write | number of bytes to write

Exceptions

  throw | DavixException if an error occurs

Create / Replace the file. Read the new content from the file descriptor fd for a maximum of size_write bytes.

Context c;
DavFile file(c, Uri(“http://example.org/file_to_create”));
int fd = open(“/tmp/file_to_upload”, O_RDONLY);
// get file size
struct stat st;
fstat(fd, &st);
// execute put
file.put(NULL, fd, static_cast<dav_size_t>(st.st_size));

Referenced by put().

## quotaInfo()

QuotaInfo & Davix::DavFile::quotaInfo | ( | const RequestParams * | params,
|  | QuotaInfo & | info )

retrieve quota information

retrieve quota information about a directory

Parameters

  params |
  info |

## readPartial()

dav_ssize_t Davix::DavFile::readPartial | ( | const RequestParams * | params,
|  | void * | buff,
|  | dav_size_t | count,
|  | dav_off_t | offset,
|  | DavixError ** | err )
throw | ( | ) |  |  |

Partial position independant read.

       Use ranged request when supported by the server,
       simulate a ranged request when not supported

Parameters

  params | Davix request Parameters
  buff | buffer
  count | maximum read size
  offset | starting offset for the read operation
  err | Davix error report

Returns
  total number of bytes read, or -1 if error occures

Context c;
char buffer[255];
DavFile file(c, Uri(“http://example.org/dir1/file_to_download”));
// get 100 bytes from http://example.org/dir1/file_to_download at offset 200
file.readPartial(NULL, buffer, 100, 200);

## readPartialBufferVec()

dav_ssize_t Davix::DavFile::readPartialBufferVec | ( | const RequestParams * | params,
|  | const DavIOVecInput * | input_vec,
|  | DavIOVecOuput * | ioutput_vec,
|  | const dav_size_t | count_vec,
|  | DavixError ** | err )
throw | ( | ) |  |  |

Vector read operation Able to do several read on several data chunk in one single operation. Uses Http multi-part when supported by the server, simulate a vector read operation otherwise.

NOTE: The return code is the number of data bytes received from the server, not the total number of bytes written into the buffers. The two might not be equal if range coalescing is performed. Check diov_size of the output vector to make sure the buffers contain the expected number of bytes.

Parameters

  params | Davix request Parameters
  input_vec | input vectors, parameters
  ioutput_vec | output vectors, results
  count_vec | number of vector
  err | Davix error report

Returns
  total number of bytes read, or -1 if error occures

Context c;
DavixError* err = NULL;
DavFile file(c, Uri("http://example.org/dir1/file_to_read"));
int number_of_vector = 2;
DavIOVecInput input_vector[number_of_vector];
DavIOVecOutput output_vector[number_of_vector];
// Setup vector operations parameters
char buf1[255] = {0};
char buf2[255] = {0};
input_vector[0].diov_offset = 100;
input_vector[0].diov_size = 200;
input_vector[0].diov_buffer = buf1;
input_vector[1].diov_offset = 600;
input_vector[1].diov_size = 150;
input_vector[1].diov_buffer = buf2;
// execute query
file.readPartialBufferVec(NULL, input_vector, output_vector, number_of_vector, &err);
std::cout << “Op 1 read ” << output_vector[0].diov_size << “bytes” << std::endl;
std::cout << “Op 2 read ” << output_vector[1].diov_size << “bytes” << std::endl;
// do things with content in output_vector[0].diov_buffer etc

## stat()

int Davix::DavFile::stat | ( | const RequestParams * | params,
|  | struct stat * | st,
|  | DavixError ** | err )
throw | ( | ) |  |  |

execute a POSIX-like stat() query

Parameters

  params | Davix request parameters
  st | stat struct
  err | Davix error report

Returns
  0 if success, or -1 if error occures

References stat().

Referenced by stat().

## statInfo()

StatInfo & Davix::DavFile::statInfo | ( | const RequestParams * | params,
|  | StatInfo & | info )

execute a file meta-data query

Parameters

  params | Davix request Parameters
  info | stat struct

Returns
  0 if success, or -1 if error occures

Contect c;
DavFile file(c, Uri(“http://example.org/dir/file_to_stat”));
StatInfo info;
file.statInfo(NULL, info);
std::cout << "my file is " << info.size << " bytes large " << std::endl;
std::cout << " mode : 0" << std::oct << info.mode << std::endl;
std::cout << " atime : " << info.atime << std::endl;
std::cout << " mtime : " << info.mtime << std::endl;
std::cout << " ctime : " << info.ctime << std::endl;

The documentation for this class was generated from the following file:

- /build/davix-vkLe3H/davix-0.8.10/include/davix/file/davfile.hpp