libfossil
fsl::Context Class Reference

C++ counterpart of fsl_cx, but generally requires less code to use because it throws exceptions for any notable errors. More...

#include "fossil.hpp"

Data Structures

class  Transaction
 A utility class for managing transactions for a Context-managed database (regardless of whether the checkout or repo db). More...
 

Public Member Functions

 Context ()
 Initializes a new fsl_cx instance, owned by this object, using the default initialization options. More...
 
 Context (fsl_cx_init_opt const &opt)
 Initializes a new fsl_cx instance, owned by this object, using the given initialization options. More...
 
 Context (fsl_cx *f, bool ownsHandle)
 Initializes this object as a wrapper of the given initialized (via fsl_cx_init()) fsl_cx handle. More...
 
 ~Context ()
 If this object owns its context handle, it fsl_cx_finalize()s it, otherwise it does nothing. More...
 
ContextcloseDbs () throw ()
 Closes any opened repo/checkout/config databases. More...
 
Dbdb () throw ()
 This returns a handle to the context's "main" database. More...
 
DbdbCheckout () throw ()
 This returns a handle to the checkout database. More...
 
DbdbRepo () throw ()
 This returns a handle to the repository database. More...
 
ContextgetContent (fsl_id_t rid, Buffer &dest)
 Analog to fsl_content_get(), but throws an error and returns this object. More...
 
ContextgetContent (char const *sym, Buffer &dest)
 Analog to fsl_content_get_sym(), but throws an error and returns this object. More...
 
ContextgetContent (std::string const &sym, Buffer &dest)
 Equivalent to getContent(sym.c_str(), dest). More...
 
fsl_cxhandle () throw ()
 Returns this object's C-level fsl_cx handle. More...
 
fsl_cx const * handle () const throw ()
 Const-correct overload. More...
 
ContextopenCheckout (char const *dirName=NULL)
 Counterpart of fsl_checkout_open_dir(). More...
 
ContextopenRepo (char const *dbFile)
 
 operator fsl_cx * () throw ()
 Implicit conversion to (fsl_cx *) to simplify usage with the C API. More...
 
 operator fsl_cx const * () const throw ()
 Const-correct overload. More...
 
bool ownsHandle () const throw ()
 Returns true if this object owns its underlying db handle, else false. More...
 
std::string ridToArtifactUuid (fsl_id_t rid, fsl_catype_t type=FSL_CATYPE_ANY)
 Like fsl_rid_to_artifact_uuid(*this, rid, type), but returns the result as a std::string and throws on error or if no entry is found. More...
 
std::string ridToUuid (fsl_id_t rid)
 Like fsl_rid_to_uuid(*this, rid), but returns the result as a std::string and throws on error or if no entry is found. More...
 
fsl_id_t symToRid (char const *symbolicName, fsl_catype_t type=FSL_CATYPE_ANY)
 Like fsl_sym_to_rid(*this,symbolicName), but throws on error or if no ID is found. More...
 
fsl_id_t symToRid (std::string const &symbolicName, fsl_catype_t type=FSL_CATYPE_ANY)
 Equivalent to symToRid(symbolicName.c_str(), type);. More...
 
std::string symToUuid (char const *symbolicName, fsl_id_t *rid=NULL, fsl_catype_t type=FSL_CATYPE_ANY)
 Like fsl_sym_to_uuid(*this,...), but returns the result as a std::string and throws on error or if no entry is found. More...
 

Detailed Description

C++ counterpart of fsl_cx, but generally requires less code to use because it throws exceptions for any notable errors.

Example:

cx.openCheckout();
fsl_uuid_cstr uuid = NULL;
fsl_id_it rid = 0;
fsl_checkout_version_info( cx, &rid, &uuid );
// ^^^ note, that's a C function!
FslOutputFStream os(cx);
os << "Checkout version: "<<rid<< ' ' << uuid << '\n';

The implicit conversion to fsl_cx makes it possible to pass instances to any C function taking such an argument (and legal to do so for most function).

Definition at line 1161 of file fossil.hpp.

Constructor & Destructor Documentation

fsl::Context::Context ( )

Initializes a new fsl_cx instance, owned by this object, using the default initialization options.

Throws on error.

fsl::Context::Context ( fsl_cx_init_opt const &  opt)
explicit

Initializes a new fsl_cx instance, owned by this object, using the given initialization options.

Throws on error.

fsl::Context::Context ( fsl_cx f,
bool  ownsHandle 
)

Initializes this object as a wrapper of the given initialized (via fsl_cx_init()) fsl_cx handle.

If ownsHandle is true then ownership of f is transfered to this object. If ownsHandle is false then this object is just a "thin" proxy for f and f MUST OUTLIVE THIS OBJECT.

fsl::Context::~Context ( )

If this object owns its context handle, it fsl_cx_finalize()s it, otherwise it does nothing.

Note that this is not virtual. It's not expected that subclassing will be all that useful for this class.

Member Function Documentation

Context& fsl::Context::closeDbs ( )
throw (
)

Closes any opened repo/checkout/config databases.

ACHTUNG: this may invalidate any Db handles pointing to them!

Returns this object.

ACHTUNG: because of ownership issues, clients must always use this function, instead of the C APIs, for closing repositories and checkouts.

Db& fsl::Context::db ( )
throw (
)

This returns a handle to the context's "main" database.

It might not be opened. The handle and its db connection are owned by this object resp. by lower levels of the API.

Db& fsl::Context::dbCheckout ( )
throw (
)

This returns a handle to the checkout database.

It might not be opened. The handle and its db connection are owned by this object resp. by lower levels of the API.

Note that if a checkout is opened, an repo will also be opened, but not necessarily the other way around.

Db& fsl::Context::dbRepo ( )
throw (
)

This returns a handle to the repository database.

It might not be opened. The handle and its db connection are owned by this object resp. by lower levels of the API.

Context& fsl::Context::getContent ( fsl_id_t  rid,
Buffer dest 
)

Analog to fsl_content_get(), but throws an error and returns this object.

Context& fsl::Context::getContent ( char const *  sym,
Buffer dest 
)

Analog to fsl_content_get_sym(), but throws an error and returns this object.

Context& fsl::Context::getContent ( std::string const &  sym,
Buffer dest 
)

Equivalent to getContent(sym.c_str(), dest).

fsl_cx* fsl::Context::handle ( )
throw (
)

Returns this object's C-level fsl_cx handle.

See operator fsl_cx *() for details.

fsl_cx const* fsl::Context::handle ( ) const
throw (
)

Const-correct overload.

Context& fsl::Context::openCheckout ( char const *  dirName = NULL)

Counterpart of fsl_checkout_open_dir().

Throws on error, returns this object on success.

Context& fsl::Context::openRepo ( char const *  dbFile)
fsl::Context::operator fsl_cx * ( )
throw (
)

Implicit conversion to (fsl_cx *) to simplify usage with the C API.

ABSOLUTELY DO NOT use this conversion...

  • ... to pass this object to fsl_cx_finalize()! Doing so will lead to a dangling pointer and an eventual segfault and/or double-free().
  • ... with fsl_checkout_close() or fsl_repo_close() because pointer ownership may get confused. Use closeDbs() instead. It will appear to work at times, but certain combinations of operations via the C API (e.g. opening a checkout, closing it, then opening a standalone repo) might get some C++-side pointers cross-wired (theoretically/hypothetically).
  • ... expect this conversion to be picked up when a function takes a void pointer argument.
fsl::Context::operator fsl_cx const * ( ) const
throw (
)

Const-correct overload.

bool fsl::Context::ownsHandle ( ) const
throw (
)

Returns true if this object owns its underlying db handle, else false.

Note that it may legally return true even when handle() returns NULL, meaning that this object is prepared to create a handle of its own if needed.

std::string fsl::Context::ridToArtifactUuid ( fsl_id_t  rid,
fsl_catype_t  type = FSL_CATYPE_ANY 
)

Like fsl_rid_to_artifact_uuid(*this, rid, type), but returns the result as a std::string and throws on error or if no entry is found.

std::string fsl::Context::ridToUuid ( fsl_id_t  rid)

Like fsl_rid_to_uuid(*this, rid), but returns the result as a std::string and throws on error or if no entry is found.

fsl_id_t fsl::Context::symToRid ( char const *  symbolicName,
fsl_catype_t  type = FSL_CATYPE_ANY 
)

Like fsl_sym_to_rid(*this,symbolicName), but throws on error or if no ID is found.

fsl_id_t fsl::Context::symToRid ( std::string const &  symbolicName,
fsl_catype_t  type = FSL_CATYPE_ANY 
)

Equivalent to symToRid(symbolicName.c_str(), type);.

std::string fsl::Context::symToUuid ( char const *  symbolicName,
fsl_id_t rid = NULL,
fsl_catype_t  type = FSL_CATYPE_ANY 
)

Like fsl_sym_to_uuid(*this,...), but returns the result as a std::string and throws on error or if no entry is found.

If rid is not NULL then on success the RID corresponding to the returned UUID is returned via *rid.


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