NetStorage

Classes
class	CNetStorageException
	Exception class for use by CNetStorage, CNetStorageByKey, and CNetStorageObject. More...
class	CNetStorageObjectInfo
	Detailed information about a CNetStorage object. More...
class	CNetStorageObject
	Basic network-based data object I/O. More...
class	CNetStorage
	Network BLOB storage API. More...
class	CNetStorageByKey
	Network BLOB storage API – with access by user-defined keys. More...

Typedefs
typedef SNetStorageObjectInfoImpl *	CNetStorageObjectInfo::TInstance
typedef unsigned	TNetStorageFlags
	Bitwise OR of ENetStorageFlags. More...
typedef SNetStorageObjectImpl *	CNetStorageObject::TInstance
typedef list< string >	CNetStorageObject::TAttributeList
	Get list of names of all attributes set on this object. More...
typedef function< void(CJsonNode)>	TNetStorageProgressCb
	Progress callback. More...
typedef SNetStorageImpl *	CNetStorage::TInstance
typedef SNetStorageByKeyImpl *	CNetStorageByKey::TInstance

Enumerations
enum	CNetStorageException::EErrCode {   CNetStorageException::eInvalidArg , CNetStorageException::eNotExists , CNetStorageException::eAuthError , CNetStorageException::eIOError ,   CNetStorageException::eServerError , CNetStorageException::eTimeout , CNetStorageException::eExpired , CNetStorageException::eNotSupported ,   CNetStorageException::eInterrupted , CNetStorageException::eUnknown }
enum	ENetStorageObjectLocation { eNFL_Unknown , eNFL_NotFound , eNFL_NetCache , eNFL_FileTrack }
	Enumeration that indicates the current location of the object. More...
enum	ENetStorageFlags {   fNST_NetCache = (1 << 0) , fNST_FileTrack = (1 << 1) , fNST_V1 , fNST_V2 = (fNST_V1 - 1) << 1 ,   fNST_Fast = fNST_NetCache , fNST_Persistent = fNST_FileTrack , fNST_AnyLoc = (fNST_V2 - 1) , fNST_Movable = (fNST_V2 << 0) ,   fNST_Cacheable = (fNST_V2 << 1) , fNST_NoMetaData = (fNST_V2 << 2) , fNST_V3 , fNST_V4 = (fNST_V3 - 1) << 1 ,   fNST_AnyAttr = (fNST_V4 - 1) ^ fNST_AnyLoc }
	Blob storage allocation and access strategy. More...
enum	ENetStorageRemoveResult { eNSTRR_NotFound , eNSTRR_Removed }
	Result returned by Remove() methods. More...

Functions
virtual const char *	CNetStorageException::GetErrCodeString () const override
	Get error code interpreted as text. More...
	CNetStorageException::NCBI_EXCEPTION_DEFAULT (CNetStorageException, CNetServiceException)
	CNetStorageObjectInfo::CNetStorageObjectInfo (EVoid)
	CNetStorageObjectInfo::CNetStorageObjectInfo (SNetStorageObjectInfoImpl *impl)
CNetStorageObjectInfo &	CNetStorageObjectInfo::operator= (SNetStorageObjectInfoImpl *impl)
	CNetStorageObjectInfo::operator SNetStorageObjectInfoImpl * ()
	CNetStorageObjectInfo::operator const SNetStorageObjectInfoImpl * () const
SNetStorageObjectInfoImpl &	CNetStorageObjectInfo::operator-- (int)
const SNetStorageObjectInfoImpl &	CNetStorageObjectInfo::operator-- (int) const
SNetStorageObjectInfoImpl *	CNetStorageObjectInfo::operator-> ()
const SNetStorageObjectInfoImpl *	CNetStorageObjectInfo::operator-> () const
	CNetStorageObjectInfo::CNetStorageObjectInfo ()
ENetStorageObjectLocation	CNetStorageObjectInfo::GetLocation () const
	Return a ENetStorageObjectLocation constant that corresponds to the storage back-end where the object currently resides. More...
CJsonNode	CNetStorageObjectInfo::GetObjectLocInfo () const
	Return a JSON object containing the fields of the object ID. More...
CTime	CNetStorageObjectInfo::GetCreationTime () const
	Return object creation time reported by the storage back-end. More...
Uint8	CNetStorageObjectInfo::GetSize () const
	Return object size in bytes. More...
CJsonNode	CNetStorageObjectInfo::GetStorageSpecificInfo () const
	Return a JSON object containing storage-specific information about the object. More...
CJsonNode	CNetStorageObjectInfo::ToJSON ()
	Pack the whole structure in a single JSON object. More...
	CNetStorageObject::CNetStorageObject (EVoid)
	CNetStorageObject::CNetStorageObject (SNetStorageObjectImpl *impl)
CNetStorageObject &	CNetStorageObject::operator= (SNetStorageObjectImpl *impl)
	CNetStorageObject::operator SNetStorageObjectImpl * ()
	CNetStorageObject::operator const SNetStorageObjectImpl * () const
SNetStorageObjectImpl &	CNetStorageObject::operator-- (int)
const SNetStorageObjectImpl &	CNetStorageObject::operator-- (int) const
SNetStorageObjectImpl *	CNetStorageObject::operator-> ()
const SNetStorageObjectImpl *	CNetStorageObject::operator-> () const
	CNetStorageObject::CNetStorageObject ()
string	CNetStorageObject::GetLoc (void) const
	Return object locator. More...
size_t	CNetStorageObject::Read (void *buffer, size_t buf_size)
	Read no more than 'buf_size' bytes of the object contents (starting at the current position) More...
void	CNetStorageObject::Read (string *data)
	Read object (starting at the current position) and put the read data into a string. More...
IReader &	CNetStorageObject::GetReader ()
	Get a reference to the IReader interface for reading the data stream of this object. More...
bool	CNetStorageObject::Eof (void)
	Check if the last Read() has hit EOF. More...
void	CNetStorageObject::Write (const void *buffer, size_t buf_size)
	Write data to the object (starting at the current position) More...
IEmbeddedStreamWriter &	CNetStorageObject::GetWriter ()
	Get a reference to the IWriter interface for storing data into this object. More...
CNcbiIostream *	CNetStorageObject::GetRWStream ()
	Get an iostream instance for reading the data stream of this NetStorage object as well as storing data into this object. More...
void	CNetStorageObject::Write (const string &data)
	Write string to the object (starting at the current position) More...
void	CNetStorageObject::Close (void)
	Finalize and close the current object stream. More...
Uint8	CNetStorageObject::GetSize (void)
	Return size of the object. More...
TAttributeList	CNetStorageObject::GetAttributeList () const
string	CNetStorageObject::GetAttribute (const string &attr_name) const
	Get the current value of the specified attribute. More...
void	CNetStorageObject::SetAttribute (const string &attr_name, const string &attr_value)
	Set the new value for the specified attribute. More...
CNetStorageObjectInfo	CNetStorageObject::GetInfo (void)
	Return detailed information about the object. More...
void	CNetStorageObject::SetExpiration (const CTimeout &ttl)
	Updates expiration on the object. More...
	CNetStorage::CNetStorage (EVoid)
	CNetStorage::CNetStorage (SNetStorageImpl *impl)
CNetStorage &	CNetStorage::operator= (SNetStorageImpl *impl)
	CNetStorage::operator SNetStorageImpl * ()
	CNetStorage::operator const SNetStorageImpl * () const
SNetStorageImpl &	CNetStorage::operator-- (int)
const SNetStorageImpl &	CNetStorage::operator-- (int) const
SNetStorageImpl *	CNetStorage::operator-> ()
const SNetStorageImpl *	CNetStorage::operator-> () const
	CNetStorage::CNetStorage (const string &init_string, TNetStorageFlags default_flags=0)
	Construct a CNetStorage object. More...
CNetStorageObject	CNetStorage::Create (TNetStorageFlags flags=0)
	Create new NetStorage object. More...
CNetStorageObject	CNetStorage::Open (const string &object_loc)
	Open an existing NetStorage object for reading. More...
string	CNetStorage::Relocate (const string &object_loc, TNetStorageFlags flags, TNetStorageProgressCb cb=TNetStorageProgressCb())
	Relocate a object according to the specified combination of flags. More...
bool	CNetStorage::Exists (const string &object_loc)
	Check if the object addressed by 'object_loc' exists. More...
ENetStorageRemoveResult	CNetStorage::Remove (const string &object_loc)
	Remove the object addressed by 'object_loc'. More...
	CNetStorageByKey::CNetStorageByKey (EVoid)
	CNetStorageByKey::CNetStorageByKey (SNetStorageByKeyImpl *impl)
CNetStorageByKey &	CNetStorageByKey::operator= (SNetStorageByKeyImpl *impl)
	CNetStorageByKey::operator SNetStorageByKeyImpl * ()
	CNetStorageByKey::operator const SNetStorageByKeyImpl * () const
SNetStorageByKeyImpl &	CNetStorageByKey::operator-- (int)
const SNetStorageByKeyImpl &	CNetStorageByKey::operator-- (int) const
SNetStorageByKeyImpl *	CNetStorageByKey::operator-> ()
const SNetStorageByKeyImpl *	CNetStorageByKey::operator-> () const
	CNetStorageByKey::CNetStorageByKey (const string &init_string, TNetStorageFlags default_flags=0)
	Construct a CNetStorageByKey object. More...
CNetStorageObject	CNetStorageByKey::Open (const string &unique_key, TNetStorageFlags flags=0)
	Create a new object or open an existing object using the supplied unique key. More...
string	CNetStorageByKey::Relocate (const string &unique_key, TNetStorageFlags flags, TNetStorageFlags old_flags=0, TNetStorageProgressCb cb=TNetStorageProgressCb())
	Relocate a object according to the specified combination of flags. More...
bool	CNetStorageByKey::Exists (const string &key, TNetStorageFlags flags=0)
	Check if a object with the specified key exists in the storage hinted by 'flags'. More...
ENetStorageRemoveResult	CNetStorageByKey::Remove (const string &key, TNetStorageFlags flags=0)
	Remove a object addressed by a key and a set of flags. More...

Variables
CNetRef< SNetStorageObjectInfoImpl >	CNetStorageObjectInfo::m_Impl
CNetRef< SNetStorageObjectImpl >	CNetStorageObject::m_Impl
CNetRef< SNetStorageImpl >	CNetStorage::m_Impl
CNetRef< SNetStorageByKeyImpl >	CNetStorageByKey::m_Impl

Detailed Description

Typedef Documentation

TAttributeList

typedef list<string> CNetStorageObject::TAttributeList

Get list of names of all attributes set on this object.

To get value of particular attribute, GetAttribute should be called.

Exceptions

If	the underlying storage does not support attributes, a CNetStorageException will be thrown.

Definition at line 300 of file netstorage.hpp.

TInstance [1/4]

typedef SNetStorageObjectInfoImpl* CNetStorageObjectInfo::TInstance

Definition at line 97 of file netstorage.hpp.

TInstance [2/4]

typedef SNetStorageObjectImpl* CNetStorageObject::TInstance

Definition at line 168 of file netstorage.hpp.

TInstance [3/4]

typedef SNetStorageImpl* CNetStorage::TInstance

Definition at line 369 of file netstorage.hpp.

TInstance [4/4]

typedef SNetStorageByKeyImpl* CNetStorageByKey::TInstance

Definition at line 472 of file netstorage.hpp.

TNetStorageFlags

typedef unsigned TNetStorageFlags

Bitwise OR of ENetStorageFlags.

Definition at line 147 of file netstorage.hpp.

TNetStorageProgressCb

typedef function<void(CJsonNode)> TNetStorageProgressCb

Progress callback.

Parameters

CJsonNode

progress info (depends on operation)

Definition at line 348 of file netstorage.hpp.

Enumeration Type Documentation

EErrCode

enum CNetStorageException::EErrCode

Enumerator
eInvalidArg	Caller passed invalid arguments to the API.
eNotExists	Illegal op applied to non-existent object.
eAuthError	Authentication error (e.g. no FileTrack API key)
eIOError	I/O error encountered while performing an op.
eServerError	NetStorage server error.
eTimeout	Timeout encountered while performing an op.
eExpired	Object has expired on server.
eNotSupported	Feature is not supported.
eInterrupted	Operation has been interrupted.
eUnknown	Unknown error.

Definition at line 69 of file netstorage.hpp.

ENetStorageFlags

enum ENetStorageFlags

Blob storage allocation and access strategy.

Enumerator
fNST_NetCache	Use NetCache as the primary storage.
fNST_FileTrack	Use FileTrack as the primary storage.
fNST_V1
fNST_V2
fNST_Fast
fNST_Persistent
fNST_AnyLoc	Any location (all location bits are set)
fNST_Movable	Allow the object to move between storages.
fNST_Cacheable	Has no effect at the moment.
fNST_NoMetaData	Do not use NetStorage relational database to track ownership & changes. Attributes and querying will also be disabled.
fNST_V3
fNST_V4
fNST_AnyAttr

Definition at line 129 of file netstorage.hpp.

ENetStorageObjectLocation

enum ENetStorageObjectLocation

Enumeration that indicates the current location of the object.

Enumerator
eNFL_Unknown
eNFL_NotFound
eNFL_NetCache
eNFL_FileTrack

Definition at line 86 of file netstorage.hpp.

ENetStorageRemoveResult

enum ENetStorageRemoveResult

Result returned by Remove() methods.

See also

CNetStorage::Remove(), CNetStorageByKey::Remove()

Enumerator
eNSTRR_NotFound	Removing failed due to object not found.
eNSTRR_Removed	Object has been removed successfully.

Definition at line 355 of file netstorage.hpp.

Function Documentation

Close()

void CNetStorageObject::Close

(

void

)

Finalize and close the current object stream.

If the operation is successful, then the state (including the current position, if applicable) of the 'CNetStorageObject' is reset, and you can start reading from (or writing to) the object all anew, as if the 'CNetStorageObject' object had just been created by 'CNetStorage'.

Exceptions

CNetStorageException

If cannot finalize writing operations

Definition at line 321 of file netstorage.cpp.

References CNetStorageObject::m_Impl.

Referenced by CProjectStorage::Clone(), CGridCommandLineInterfaceApp::Cmd_Download(), CGridCommandLineInterfaceApp::Cmd_Upload(), CNetCacheBlobFetchApp::ProcessRequest(), CNetStorageObject::Read(), CProjectStorage::SaveObject(), CProjectStorage::SaveProject(), CProjectStorage::SaveRawData(), CProjectStorage::SaveStream(), CProjectStorage::SaveString(), CNetStorageHandler::x_ProcessRead(), CNetStorageHandler::x_SendWriteConfirmation(), and SNetStorageObjectRWStream::~SNetStorageObjectRWStream().

CNetStorage() [1/3]

CNetStorage::CNetStorage ( const string &  init_string, TNetStorageFlags  default_flags = 0  )

explicit

Construct a CNetStorage object.

Parameters

init_string

Initialization string that contains client identification, network service locations, etc. The string must be a sequence of apersand-separated pairs of attribute names and their values. Within each pair, the name and the value of the attribute must be separated by the equality sign, and the value must be URL-encoded. The following attributes are recoginzed: * namespace - Application domain. This parameter is required. * client - Application name. If omitted, generated from the executable pathname. * nst - NetStorage server address or LBSM service name pointing to a group of NetStorage servers. * metadata - Whether to request or disable the metadata DB. Valid options: required - Database access must be enabled for the specified NetStorage service name in the server configuration. disabled - Database access is disabled for all operations. monitoring - Read-only access to the metadata database. * nc - NetCache service name or server address. * cache - Synonym for "namespace". Example: "client=MyApp&nst=NST_Test&nc=NC_MyApp_TEST&cache=myapp"

default_flags

Default storage preferences for the created objects.

Definition at line 326 of file netstorage.cpp.

CNetStorage() [2/3]

CNetStorage::CNetStorage ( EVoid  )

inline

Definition at line 369 of file netstorage.hpp.

CNetStorage() [3/3]

CNetStorage::CNetStorage ( SNetStorageImpl *  impl )

inline

Definition at line 369 of file netstorage.hpp.

CNetStorageByKey() [1/3]

CNetStorageByKey::CNetStorageByKey ( const string &  init_string, TNetStorageFlags  default_flags = 0  )

explicit

Construct a CNetStorageByKey object.

Parameters

init_string

Initialization string that contains client identification, network service locations, etc. The string must be a sequence of apersand-separated pairs of attribute names and their values. Within each pair, the name and the value of the attribute must be separated by the equality sign, and the value must be URL-encoded. The following attributes are recoginzed: * namespace - Namespace name, within which the keys passed to the methods of this class must be unique. This parameter is required. * domain - Synonym for "namespace". * client - Application name. * nst - NetStorage server address or LBSM service name pointing to a group of NetStorage servers. Example: "client=MyApp&nst=NST_Test&namespace=myapp"

default_flags

Default storage preferences for objects created by this object.

Definition at line 361 of file netstorage.cpp.

CNetStorageByKey() [2/3]

CNetStorageByKey::CNetStorageByKey ( EVoid  )

inline

Definition at line 472 of file netstorage.hpp.

CNetStorageByKey() [3/3]

CNetStorageByKey::CNetStorageByKey ( SNetStorageByKeyImpl *  impl )

inline

Definition at line 472 of file netstorage.hpp.

CNetStorageObject() [1/3]

CNetStorageObject::CNetStorageObject ( )

inline

Definition at line 168 of file netstorage.hpp.

CNetStorageObject() [2/3]

CNetStorageObject::CNetStorageObject ( EVoid  )

inline

Definition at line 168 of file netstorage.hpp.

CNetStorageObject() [3/3]

CNetStorageObject::CNetStorageObject ( SNetStorageObjectImpl *  impl )

inline

Definition at line 168 of file netstorage.hpp.

CNetStorageObjectInfo() [1/3]

CNetStorageObjectInfo::CNetStorageObjectInfo ( )

inline

Definition at line 97 of file netstorage.hpp.

CNetStorageObjectInfo() [2/3]

CNetStorageObjectInfo::CNetStorageObjectInfo ( EVoid  )

inline

Definition at line 97 of file netstorage.hpp.

CNetStorageObjectInfo() [3/3]

CNetStorageObjectInfo::CNetStorageObjectInfo ( SNetStorageObjectInfoImpl *  impl )

inline

Definition at line 97 of file netstorage.hpp.

Create()

CNetStorageObject CNetStorage::Create

(

TNetStorageFlags

flags = 0

)

Create new NetStorage object.

The physical storage is allocated during the first CNetStorageObject::Write() operation.

Parameters

flags

Combination of flags that defines object location (storage) and caching

Returns

New CNetStorageObject

Definition at line 333 of file netstorage.cpp.

References flags, and CNetStorage::m_Impl.

Referenced by CProjectStorage::Clone(), CGridCommandLineInterfaceApp::GetNetStorageObject(), CProjectStorage::SaveRawData(), and CProjectStorage::x_GetOutputStream().

Eof()

bool CNetStorageObject::Eof

(

void

)

Check if the last Read() has hit EOF.

Returns

TRUE if if the last Read() has hit EOF; FALSE otherwise

Exceptions

CNetStorageException

If the object doesn't exist, or if 'CNetStorageObject' is in writing mode

Definition at line 260 of file netstorage.cpp.

References SNetStorageObjectIoMode::eBuffer, SNetStorageObjectIoMode::eEof, and CNetStorageObject::m_Impl.

Referenced by CGridCommandLineInterfaceApp::Cmd_Download(), CNetCacheBlobFetchApp::ProcessRequest(), CNetStorageObject::Read(), and CNetStorageHandler::x_ProcessRead().

Exists() [1/2]

bool CNetStorageByKey::Exists	(	const string &	key,
		TNetStorageFlags	flags = 0
	)

Check if a object with the specified key exists in the storage hinted by 'flags'.

Returns

TRUE if the object exists; FALSE otherwise

Definition at line 383 of file netstorage.cpp.

References flags, ncbi::grid::netcache::search::fields::key, and CNetStorageByKey::Open().

Exists() [2/2]

bool CNetStorage::Exists

(

const string &

object_loc

)

Check if the object addressed by 'object_loc' exists.

Parameters

object_loc

File to check for existence

Returns

TRUE if the object exists; FALSE otherwise

Definition at line 349 of file netstorage.cpp.

References CNetStorage::Open().

Referenced by CProjectStorage::Exists(), and CNetStorageGCApp::x_CheckExpiration().

GetAttribute()

string CNetStorageObject::GetAttribute

(

const string &

attr_name

)

const

Get the current value of the specified attribute.

Attribute values are not cached by this method.

Exceptions

If	the underlying storage does not support attributes, a CNetStorageException will be thrown.

Definition at line 300 of file netstorage.cpp.

References CNetStorageObject::m_Impl.

Referenced by CGridCommandLineInterfaceApp::Cmd_GetAttr(), and NAutomation::SNetStorageObject::ExecGetAttr().

GetAttributeList()

CNetStorageObject::TAttributeList CNetStorageObject::GetAttributeList

(

)

const

Definition at line 295 of file netstorage.cpp.

References CNetStorageObject::m_Impl.

Referenced by CGridCommandLineInterfaceApp::Cmd_GetAttrList(), and NAutomation::SNetStorageObject::ExecAttrList().

GetCreationTime()

CTime CNetStorageObjectInfo::GetCreationTime

(

)

const

Return object creation time reported by the storage back-end.

Note

Valid only if GetLocation() != eNFL_NotFound.

Definition at line 260 of file netstorageobjectinfo.cpp.

References CNetStorageObjectInfo::m_Impl.

GetErrCodeString()

const char * CNetStorageException::GetErrCodeString ( void  ) const

overridevirtual

Get error code interpreted as text.

Reimplemented from CNetServiceException.

Definition at line 58 of file netstorage_rpc.cpp.

References CNetStorageException::eAuthError, CNetStorageException::eExpired, CNetStorageException::eInterrupted, CNetStorageException::eInvalidArg, CNetStorageException::eIOError, CNetStorageException::eNotExists, CNetStorageException::eNotSupported, CNetStorageException::eServerError, CNetStorageException::eTimeout, CNetStorageException::eUnknown, CException::GetErrCode(), and CException::GetErrCodeString().

GetInfo()

CNetStorageObjectInfo CNetStorageObject::GetInfo

(

void

)

Return detailed information about the object.

Returns

A CNetStorageObjectInfo object. If the object is not found, a valid object is returned, which returns eNFL_NotFound for GetLocation().

Exceptions

CNetStorageException

on error

See also

CNetStorageObjectInfo

Definition at line 311 of file netstorage.cpp.

References CNetStorageObject::m_Impl.

Referenced by CGridCommandLineInterfaceApp::Cmd_NetStorageObjectInfo(), NAutomation::SNetStorageObject::ExecInfo(), and CNetStorageHandler::x_ProcessGetObjectInfo().

GetLoc()

string CNetStorageObject::GetLoc

(

void

)

const

Return object locator.

Definition at line 224 of file netstorage.cpp.

References CNetStorageObject::m_Impl.

Referenced by CProjectStorage::Clone(), CGridCommandLineInterfaceApp::Cmd_Upload(), CProjectStorage::SaveRawData(), CProjectStorage::x_GetOutputStream(), CNetStorageHandler::x_OnData(), CNetStorageHandler::x_ProcessCreate(), and CNetStorageHandler::x_SendWriteConfirmation().

GetLocation()

TLocation CNetStorageObjectInfo::GetLocation

(

void

)

const

Return a ENetStorageObjectLocation constant that corresponds to the storage back-end where the object currently resides.

If the object cannot be found in any of the predictable locations, eNFL_NotFound is returned. If the object is found, the returned value reflects the storage back-end that supplied the rest of information about the object.

Definition at line 250 of file netstorageobjectinfo.cpp.

References CNetStorageObjectInfo::m_Impl.

GetObjectLocInfo()

CJsonNode CNetStorageObjectInfo::GetObjectLocInfo

(

)

const

Return a JSON object containing the fields of the object ID.

A valid value is returned even if GetLocation() == eNFL_NotFound.

Definition at line 255 of file netstorageobjectinfo.cpp.

References CNetStorageObjectInfo::m_Impl.

GetReader()

IReader & CNetStorageObject::GetReader

(

)

Get a reference to the IReader interface for reading the data stream of this object.

The returned reference can be fed to a CRStream object to turn it into an std::istream. In this case, please make sure the CRWStreambuf::fOwnReader flag is NOT used. It is, however, better to use the GetRWStream() method for this purpose.

See also

GetRWStream()

Definition at line 254 of file netstorage.cpp.

References SNetStorageObjectIoMode::eIReaderIWriter, SNetStorageObjectIoMode::eRead, and CNetStorageObject::m_Impl.

Referenced by CProjectStorage::Clone().

GetRWStream()

CNcbiIostream * CNetStorageObject::GetRWStream

(

)

Get an iostream instance for reading the data stream of this NetStorage object as well as storing data into this object.

The returned iostream object must be deleted by the caller.

Warning

Empty writes are ignored by the returned iostream instance!

Definition at line 284 of file netstorage.cpp.

References SNetStorageObjectIoMode::eAnyMth, SNetStorageObjectIoMode::eIoStream, and CNetStorageObject::m_Impl.

Referenced by CProjectStorage::GetIstream(), and CProjectStorage::x_GetOutputStream().

GetSize() [1/2]

Uint8 CNetStorageObjectInfo::GetSize

(

void

)

const

Return object size in bytes.

Note

Valid only if GetLocation() != eNFL_NotFound.

Definition at line 265 of file netstorageobjectinfo.cpp.

References CNetStorageObjectInfo::m_Impl.

GetSize() [2/2]

Uint8 CNetStorageObject::GetSize

(

void

)

Return size of the object.

Returns

Size of the object in bytes

Exceptions

CNetStorageException

On any error (including if the object does not yet exist)

Definition at line 290 of file netstorage.cpp.

References CNetStorageObject::m_Impl.

Referenced by CNetStorageHandler::x_ProcessGetSize().

GetStorageSpecificInfo()

CJsonNode CNetStorageObjectInfo::GetStorageSpecificInfo

(

)

const

Return a JSON object containing storage-specific information about the object.

Note

Valid only if GetLocation() != eNFL_NotFound.

Definition at line 270 of file netstorageobjectinfo.cpp.

References CNetStorageObjectInfo::m_Impl.

GetWriter()

IEmbeddedStreamWriter & CNetStorageObject::GetWriter

(

)

Get a reference to the IWriter interface for storing data into this object.

The returned reference can be fed to a CWStream object to turn it into an std::ostream. In this case, please make sure the CRWStreambuf::fOwnWriter flag is NOT used. It is, however, better to use the GetRWStream() method for this purpose.

Note

The IEmbeddedStreamWriter::Close() method must be explicitly called in order to catch the errors that may happen during object finalization.

See also

GetRWStream()

Definition at line 278 of file netstorage.cpp.

References SNetStorageObjectIoMode::eIReaderIWriter, SNetStorageObjectIoMode::eWrite, and CNetStorageObject::m_Impl.

Referenced by CProjectStorage::Clone(), and CProjectStorage::SaveRawData().

NCBI_EXCEPTION_DEFAULT()

CNetStorageException::NCBI_EXCEPTION_DEFAULT	(	CNetStorageException	,
		CNetServiceException
	)

Open() [1/2]

CNetStorageObject CNetStorage::Open

(

const string &

object_loc

)

Open an existing NetStorage object for reading.

Note

The object is not checked for existence until CNetStorageObject::Read() is called

Parameters

object_loc

File to open

Returns

New CNetStorageObject

Definition at line 338 of file netstorage.cpp.

References CNetStorage::m_Impl.

Referenced by CProjectStorage::Clone(), CNetStorage::Exists(), CProjectStorage::GetIstream(), CGridCommandLineInterfaceApp::GetNetStorageObject(), CNetCacheBlobFetchApp::ProcessRequest(), CNetStorage::Relocate(), CNetStorage::Remove(), CProjectStorage::SaveRawData(), and CProjectStorage::x_GetOutputStream().

Open() [2/2]

CNetStorageObject CNetStorageByKey::Open	(	const string &	unique_key,
		TNetStorageFlags	flags = 0
	)

Create a new object or open an existing object using the supplied unique key.

The returned object object can be either written or read.

Parameters

key	User-defined unique key that, in combination with the domain name specified in the constructor, can be used to address the object
flags	Combination of flags that defines object location and caching.

Returns

New CNetStorageObject.

Definition at line 368 of file netstorage.cpp.

References flags, and CNetStorageByKey::m_Impl.

Referenced by CNetStorageByKey::Exists(), CGridCommandLineInterfaceApp::GetNetStorageObject(), CNetStorageByKey::Relocate(), and CNetStorageByKey::Remove().

operator const SNetStorageByKeyImpl *()

CNetStorageByKey::operator const SNetStorageByKeyImpl * ( ) const

inline

Definition at line 472 of file netstorage.hpp.

operator const SNetStorageImpl *()

CNetStorage::operator const SNetStorageImpl * ( ) const

inline

Definition at line 369 of file netstorage.hpp.

operator const SNetStorageObjectImpl *()

CNetStorageObject::operator const SNetStorageObjectImpl * ( ) const

inline

Definition at line 168 of file netstorage.hpp.

operator const SNetStorageObjectInfoImpl *()

CNetStorageObjectInfo::operator const SNetStorageObjectInfoImpl * ( ) const

inline

Definition at line 97 of file netstorage.hpp.

operator SNetStorageByKeyImpl *()

CNetStorageByKey::operator SNetStorageByKeyImpl * ( )

inline

Definition at line 472 of file netstorage.hpp.

operator SNetStorageImpl *()

CNetStorage::operator SNetStorageImpl * ( )

inline

Definition at line 369 of file netstorage.hpp.

operator SNetStorageObjectImpl *()

CNetStorageObject::operator SNetStorageObjectImpl * ( )

inline

Definition at line 168 of file netstorage.hpp.

operator SNetStorageObjectInfoImpl *()

CNetStorageObjectInfo::operator SNetStorageObjectInfoImpl * ( )

inline

Definition at line 97 of file netstorage.hpp.

operator--() [1/8]

SNetStorageObjectInfoImpl& CNetStorageObjectInfo::operator-- ( int  )

inline

Definition at line 97 of file netstorage.hpp.

operator--() [2/8]

SNetStorageObjectImpl& CNetStorageObject::operator-- ( int  )

inline

Definition at line 168 of file netstorage.hpp.

operator--() [3/8]

SNetStorageImpl& CNetStorage::operator-- ( int  )

inline

Definition at line 369 of file netstorage.hpp.

operator--() [4/8]

SNetStorageByKeyImpl& CNetStorageByKey::operator-- ( int  )

inline

Definition at line 472 of file netstorage.hpp.

operator--() [5/8]

const SNetStorageObjectInfoImpl& CNetStorageObjectInfo::operator-- ( int  ) const

inline

Definition at line 97 of file netstorage.hpp.

operator--() [6/8]

const SNetStorageObjectImpl& CNetStorageObject::operator-- ( int  ) const

inline

Definition at line 168 of file netstorage.hpp.

operator--() [7/8]

const SNetStorageImpl& CNetStorage::operator-- ( int  ) const

inline

Definition at line 369 of file netstorage.hpp.

operator--() [8/8]

const SNetStorageByKeyImpl& CNetStorageByKey::operator-- ( int  ) const

inline

Definition at line 472 of file netstorage.hpp.

operator->() [1/8]

SNetStorageObjectInfoImpl* CNetStorageObjectInfo::operator-> ( void  )

inline

Definition at line 97 of file netstorage.hpp.

operator->() [2/8]

SNetStorageObjectImpl* CNetStorageObject::operator-> ( void  )

inline

Definition at line 168 of file netstorage.hpp.

operator->() [3/8]

SNetStorageImpl* CNetStorage::operator-> ( void  )

inline

Definition at line 369 of file netstorage.hpp.

operator->() [4/8]

SNetStorageByKeyImpl* CNetStorageByKey::operator-> ( void  )

inline

Definition at line 472 of file netstorage.hpp.

operator->() [5/8]

const SNetStorageObjectInfoImpl* CNetStorageObjectInfo::operator-> ( void  ) const

inline

Definition at line 97 of file netstorage.hpp.

operator->() [6/8]

const SNetStorageObjectImpl* CNetStorageObject::operator-> ( void  ) const

inline

Definition at line 168 of file netstorage.hpp.

operator->() [7/8]

const SNetStorageImpl* CNetStorage::operator-> ( void  ) const

inline

Definition at line 369 of file netstorage.hpp.

operator->() [8/8]

const SNetStorageByKeyImpl* CNetStorageByKey::operator-> ( void  ) const

inline

Definition at line 472 of file netstorage.hpp.

operator=() [1/4]

CNetStorageByKey& CNetStorageByKey::operator= ( SNetStorageByKeyImpl *  impl )

inline

Definition at line 472 of file netstorage.hpp.

operator=() [2/4]

CNetStorage& CNetStorage::operator= ( SNetStorageImpl *  impl )

inline

Definition at line 369 of file netstorage.hpp.

operator=() [3/4]

CNetStorageObject& CNetStorageObject::operator= ( SNetStorageObjectImpl *  impl )

inline

Definition at line 168 of file netstorage.hpp.

operator=() [4/4]

CNetStorageObjectInfo& CNetStorageObjectInfo::operator= ( SNetStorageObjectInfoImpl *  impl )

inline

Definition at line 97 of file netstorage.hpp.

Read() [1/2]

void CNetStorageObject::Read

(

string *

data

)

Read object (starting at the current position) and put the read data into a string.

Parameters

data	The string in which to store the read data

Exceptions

CNetStorageException

If unable to read ALL of the data, or if 'CNetStorageObject' is in writing mode

Definition at line 237 of file netstorage.cpp.

References buffer, CNetStorageObject::Close(), data, CNetStorageObject::Eof(), SNetStorageObjectIoMode::eRead, SNetStorageObjectIoMode::eString, and CNetStorageObject::m_Impl.

Read() [2/2]

size_t CNetStorageObject::Read	(	void *	buffer,
		size_t	buf_size
	)

Read no more than 'buf_size' bytes of the object contents (starting at the current position)

Parameters

buffer	Pointer to the receiving buffer. NULL means to skip bytes (advance the current object reading position by 'buf_size' bytes).
buf_size	Number of bytes to attempt to read (or to skip)

Returns

Number of bytes actually read into the receiving buffer (or skipped)

Exceptions

CNetStorageException

On any error – and only if no data at all has been actually read. Also, if 'CNetStorageObject' is in writing mode.

Definition at line 229 of file netstorage.cpp.

References buffer, SNetStorageObjectIoMode::eBuffer, SNetStorageObjectIoMode::eRead, and CNetStorageObject::m_Impl.

Referenced by CGridCommandLineInterfaceApp::Cmd_Download(), CNetCacheBlobFetchApp::ProcessRequest(), and CNetStorageHandler::x_ProcessRead().

Relocate() [1/2]

string CNetStorage::Relocate	(	const string &	object_loc,
		TNetStorageFlags	flags,
		TNetStorageProgressCb	cb = TNetStorageProgressCb()
	)

Relocate a object according to the specified combination of flags.

Parameters

object_loc	An existing object to relocate
flags	Combination of flags that defines the new object location (storage)
cb	Relocation progress callback (

See also

TNetStorageProgressCb). CJsonNode input argument (object) will contain two subnodes: number 'BytesRelocated' and string 'Message'

Returns

New object ID that fully reflects the new object location. If possible, this new ID should be used for further access to the object. Note however that its original ID still can be used as well.

Definition at line 343 of file netstorage.cpp.

References flags, and CNetStorage::Open().

Referenced by CGridCommandLineInterfaceApp::Cmd_Relocate().

Relocate() [2/2]

string CNetStorageByKey::Relocate	(	const string &	unique_key,
		TNetStorageFlags	flags,
		TNetStorageFlags	old_flags = 0,
		TNetStorageProgressCb	cb = TNetStorageProgressCb()
	)

Relocate a object according to the specified combination of flags.

Parameters

flags	Combination of flags that defines the new object location
old_flags	Combination of flags that defines the current object location
cb	Relocation progress callback (

See also

TNetStorageProgressCb). CJsonNode input argument (object) will contain two subnodes: number 'BytesRelocated' and string 'Message'

Returns

A unique full object ID that reflects the new object location (storage) and which can be used with CNetStorage::Open(). Note however that the original ID 'unique_key' still can be used as well.

Definition at line 375 of file netstorage.cpp.

References flags, and CNetStorageByKey::Open().

Referenced by CGridCommandLineInterfaceApp::Cmd_Relocate().

Remove() [1/2]

ENetStorageRemoveResult CNetStorageByKey::Remove	(	const string &	key,
		TNetStorageFlags	flags = 0
	)

Remove a object addressed by a key and a set of flags.

Parameters

key	User-defined unique key that, in combination with the domain name specified in the constructor, addresses the object
flags	Combination of flags that hints on the current object location

Definition at line 389 of file netstorage.cpp.

References flags, ncbi::grid::netcache::search::fields::key, and CNetStorageByKey::Open().

Referenced by CGridCommandLineInterfaceApp::Cmd_RemoveNetStorageObject().

Remove() [2/2]

ENetStorageRemoveResult CNetStorage::Remove

(

const string &

object_loc

)

Remove the object addressed by 'object_loc'.

Parameters

object_loc

File to remove

Definition at line 355 of file netstorage.cpp.

References CNetStorage::Open().

Referenced by CGridCommandLineInterfaceApp::Cmd_RemoveNetStorageObject(), CProjectStorage::Delete(), and CNetStorageGCApp::x_RemoveObjects().

SetAttribute()

void CNetStorageObject::SetAttribute	(	const string &	attr_name,
		const string &	attr_value
	)

Set the new value for the specified attribute.

Exceptions

If	the underlying storage does not support attributes, a CNetStorageException will be thrown.

Definition at line 305 of file netstorage.cpp.

References CNetStorageObject::m_Impl.

Referenced by CGridCommandLineInterfaceApp::Cmd_SetAttr(), and CProjectStorage::SaveObject().

SetExpiration()

void CNetStorageObject::SetExpiration

(

const CTimeout &

ttl

)

Updates expiration on the object.

Parameters

ttl	Expiration timeout, may be infinite

Exceptions

If	the underlying storage does not support expiration, a CNetStorageException will be thrown.

Definition at line 316 of file netstorage.cpp.

References CNetStorageObject::m_Impl.

Referenced by CProjectStorage::Clone(), CGridCommandLineInterfaceApp::Cmd_Upload(), CProjectStorage::SaveObject(), CProjectStorage::SaveProject(), CProjectStorage::SaveRawData(), CProjectStorage::SaveStream(), CProjectStorage::SaveString(), CNetStorageHandler::x_ProcessGetSize(), and CNetStorageHandler::x_ProcessSetExpTime().

ToJSON()

CJsonNode CNetStorageObjectInfo::ToJSON

(

)

Pack the whole structure in a single JSON object.

Definition at line 275 of file netstorageobjectinfo.cpp.

References CNetStorageObjectInfo::m_Impl.

Referenced by CGridCommandLineInterfaceApp::Cmd_NetStorageObjectInfo(), NAutomation::SNetStorageObject::ExecInfo(), and CNetStorageHandler::x_ProcessGetObjectInfo().

Write() [1/2]

void CNetStorageObject::Write

(

const string &

data

)

Write string to the object (starting at the current position)

Parameters

data	Data to write to the object

Exceptions

CNetStorageException

If unable to write ALL of the data, or if CNetStorageObject is in reading mode

Definition at line 272 of file netstorage.cpp.

References data, SNetStorageObjectIoMode::eString, SNetStorageObjectIoMode::eWrite, CNetStorageObject::m_Impl, and NULL.

Write() [2/2]

void CNetStorageObject::Write	(	const void *	buffer,
		size_t	buf_size
	)

Write data to the object (starting at the current position)

Parameters

buffer	Pointer to the data to write
buf_size	Data length in bytes

Exceptions

CNetStorageException

If unable to write ALL of the data, or if CNetStorageObject is in reading mode

Definition at line 266 of file netstorage.cpp.

References buffer, SNetStorageObjectIoMode::eBuffer, SNetStorageObjectIoMode::eWrite, CNetStorageObject::m_Impl, and NULL.

Referenced by CGridCommandLineInterfaceApp::Cmd_Upload(), CProjectStorage::SaveRawData(), CNetStorageHandler::x_OnData(), and CNetStorageHandler::x_SendWriteConfirmation().

Variable Documentation

m_Impl [1/4]

CNetRef< SNetStorageObjectInfoImpl > CNetStorageObjectInfo::m_Impl

protected

Definition at line 97 of file netstorage.hpp.

Referenced by CNetStorageObjectInfo::GetCreationTime(), CNetStorageObjectInfo::GetLocation(), CNetStorageObjectInfo::GetObjectLocInfo(), CNetStorageObjectInfo::GetSize(), CNetStorageObjectInfo::GetStorageSpecificInfo(), and CNetStorageObjectInfo::ToJSON().

m_Impl [2/4]

CNetRef< SNetStorageObjectImpl > CNetStorageObject::m_Impl

protected

Definition at line 168 of file netstorage.hpp.

Referenced by CDirectNetStorageObject::CancelRelocate(), CNetStorageObject::Close(), CNetStorageObject::Eof(), CDirectNetStorageObject::FileTrack_Path(), CNetStorageObject::GetAttribute(), CNetStorageObject::GetAttributeList(), CNetStorageObject::GetInfo(), CNetStorageObject::GetLoc(), CNetStorageObject::GetReader(), CNetStorageObject::GetRWStream(), CNetStorageObject::GetSize(), CDirectNetStorageObject::GetUserInfo(), CNetStorageObject::GetWriter(), CDirectNetStorageObject::Locator(), CNetStorageObject::Read(), CDirectNetStorageObject::Relocate(), CDirectNetStorageObject::Remove(), CNetStorageObject::SetAttribute(), CNetStorageObject::SetExpiration(), and CNetStorageObject::Write().

m_Impl [3/4]

CNetRef< SNetStorageImpl > CNetStorage::m_Impl

protected

Definition at line 369 of file netstorage.hpp.

Referenced by CDirectNetStorage::Create(), CNetStorage::Create(), CDirectNetStorage::Exists(), CNetStorage::Open(), CDirectNetStorage::Open(), and CDirectNetStorage::ReportConfig().

m_Impl [4/4]

CNetRef< SNetStorageByKeyImpl > CNetStorageByKey::m_Impl

protected

Definition at line 472 of file netstorage.hpp.

Referenced by CDirectNetStorageByKey::Exists(), CNetStorageByKey::Open(), and CDirectNetStorageByKey::Open().