Classes | Modules | Typedefs | Enumerations | Enumerator | Functions

Named Stream Management
[General Utility Libraries]

Simple library to abstract read-only hierarchies of named streams. More...

Collaboration diagram for Named Stream Management:

Classes

class  nstream::Stream
 an instance of a read-only stream More...
class  nstream::Entry
 a generic entry in the namespace. This is either a Folder or File More...
class  nstream::File
 an atom in the namespace: a File is a named object from which you can request read-only streams. More...
class  nstream::Folder
 a folder in the namespace: contains other stream::Entry objects. More...
class  nstream::Manager
 the object that manages a particular space of named streams More...

Modules

 Named Streams: Filesystem
 

This is a reference implemenation of the nstream interface, for a local filesystem.


Typedefs

typedef eIterationFlag(* nstream::visit_entry_fn )(IN Entry *entry, IN void *context)
 callback for nstream::walkChildFolders()

Enumerations

enum  nstream::eIterationFlag {
  nstream::eIterate_Continue = 1,
  nstream::eIterate_Stop = 2,
  nstream::eIterate_Invalid = 0
}
 

used by nstream::walkChildFolders() callback

More...

Functions

virtual std::istream & nstream::Stream::getStream (void)=0
 get access to the raw data stream
virtual smart_ptr< File > nstream::Stream::getFile (void)=0
 get a pointer to the nstream::File object with which this Stream is associated.
virtual void nstream::Stream::writeDiagnostics (IO std::ostream &out)
 helper method to get diagnostic information during errors etc
 nstream::Stream::operator std::istream & (void)
bool nstream::Stream::eof (void)
bool nstream::Stream::good (void)
bool nstream::Stream::bad (void)
virtual nstream::Entry::~Entry (void) throw ()
virtual eType nstream::Entry::getType (void) const =0 throw ()
 what type of entry is this?
virtual const char * nstream::Entry::getName (void) const =0 throw ()
 this Entry's name in the namespace (that is, relative to the root of the namespace).
virtual smart_ptr< Manager > nstream::Entry::getManager (void)=0
 the Manager of this namespace
virtual smart_ptr< Stream > nstream::File::openStream (void)=0
 creates a new instance of a read-only stream for this File's data
virtual smart_ptr< Entry > nstream::Folder::getChildByName (IN const char *name)=0
 get a child entry directly by its name relative to the parent (returns NULL if no such child exists)
virtual void nstream::Folder::resetIteration (void)=0
 reset the Folder iteration to point to the first Entry again.
virtual smart_ptr< Entry > nstream::Folder::getNextChild (void)=0
 get the next child Entry object. Returns null when done.
virtual smart_ptr< Entry > nstream::Manager::getEntry (IN const char *name)=0
 get the entry with the given name.
virtual smart_ptr< Folder > nstream::Manager::getRoot (void)=0
 get the root Folder object for this namespace
virtual std::string nstream::Manager::getFullName (IN const char *name)=0
 get the full name (absolute path, URL, ...) for this name
smart_ptr< Stream > nstream::getStreamRelativeTo (IN Stream *startStream, IN const char *relativePath)
 Helper method: given a Stream object, and a path relative to that stream path, return a stream for that.
smart_ptr< Stream > nstream::openNamedStream (IN Manager *mgr, IN const char *name)
 Helper method: open a Stream for a given path on the specified Manager.
std::string nstream::getStreamName (IN Stream *stream)
 Helper method: given a Stream, return its name.
eIterationFlag nstream::walkChildFolders (IN Folder *root, IN visit_entry_fn callback, IN void *context, IN const SetString *extensions=NULL, IN const char *filter=NULL, IN bool visitHidden=false)
 helper methods: given a Folder, walk all child Folders and Entries recursively.



smart_ptr< Manager > nstream::getResourceStreamManager (void)

Detailed Description

Simple library to abstract read-only hierarchies of named streams.

By "hierarchy of named streams", this refers to any set of resources that have folder/file semantics, but may not be filesystems. Concrete examples may be:

Why should code use this library? This is handy if you have code that needs to know about multiple streams with relative paths, but should be abstracted from the physical details of where the streams are. One example I've hit lately is a library that parses and displays 3D models. You'll want that code to be able to access streams to read the data and display, but you wouldn't want to limit that library to only work on a local filesystem.

Why read-only? Why can't you use this library to create and write new files? Allowing modifications starts getting complex. For instance, creating and writing new files to a remote webserver may require special protocols depending on the server. And writeable access to a compressed archive may not be possible at all (it could require that the archive be completely rebuilt). In the future write concepts may be included, but for now all use cases are read-only.

How do you use this library? First, get or create a Manager object. From there, you can either look up Entry objects by name, or you can start iterating over folders to discover Entry objects, starting with getRoot().


Typedef Documentation

typedef eIterationFlag(* nstream::visit_entry_fn)(IN Entry *entry, IN void *context)

callback for nstream::walkChildFolders()

Definition at line 293 of file nstream.h.


Enumeration Type Documentation

used by nstream::walkChildFolders() callback

Enumerator:
eIterate_Continue 

keep iterating through entries

eIterate_Stop 

stop iterating

eIterate_Invalid 

Definition at line 283 of file nstream.h.


Function Documentation

virtual std::istream& nstream::Stream::getStream ( void   )  [pure virtual, inherited]

get access to the raw data stream

virtual smart_ptr<File> nstream::Stream::getFile ( void   )  [pure virtual, inherited]

get a pointer to the nstream::File object with which this Stream is associated.

void nstream::Stream::writeDiagnostics ( IO std::ostream &  out  )  [virtual, inherited]

helper method to get diagnostic information during errors etc

Definition at line 114 of file nstream.cpp.

nstream::Stream::operator std::istream & ( void   )  [inline, inherited]

Definition at line 120 of file nstream.h.

bool nstream::Stream::eof ( void   )  [inline, inherited]

Definition at line 121 of file nstream.h.

bool nstream::Stream::good ( void   )  [inline, inherited]

Definition at line 122 of file nstream.h.

bool nstream::Stream::bad ( void   )  [inline, inherited]

Definition at line 123 of file nstream.h.

nstream::Entry::~Entry ( void   )  throw () [virtual, inherited]

Definition at line 47 of file nstream.cpp.

virtual eType nstream::Entry::getType ( void   )  const throw () [pure virtual, inherited]

what type of entry is this?

virtual const char* nstream::Entry::getName ( void   )  const throw () [pure virtual, inherited]

this Entry's name in the namespace (that is, relative to the root of the namespace).

virtual smart_ptr<Manager> nstream::Entry::getManager ( void   )  [pure virtual, inherited]

the Manager of this namespace

virtual smart_ptr<Stream> nstream::File::openStream ( void   )  [pure virtual, inherited]

creates a new instance of a read-only stream for this File's data

virtual smart_ptr<Entry> nstream::Folder::getChildByName ( IN const char *  name  )  [pure virtual, inherited]

get a child entry directly by its name relative to the parent (returns NULL if no such child exists)

virtual void nstream::Folder::resetIteration ( void   )  [pure virtual, inherited]

reset the Folder iteration to point to the first Entry again.

virtual smart_ptr<Entry> nstream::Folder::getNextChild ( void   )  [pure virtual, inherited]

get the next child Entry object. Returns null when done.

virtual smart_ptr<Entry> nstream::Manager::getEntry ( IN const char *  name  )  [pure virtual, inherited]

get the entry with the given name.

Returns NULL if there is no entry with that name.

virtual smart_ptr<Folder> nstream::Manager::getRoot ( void   )  [pure virtual, inherited]

get the root Folder object for this namespace

virtual std::string nstream::Manager::getFullName ( IN const char *  name  )  [pure virtual, inherited]

get the full name (absolute path, URL, ...) for this name

smart_ptr< Stream > nstream::getStreamRelativeTo ( IN Stream *  startStream,
IN const char *  relativePath 
)

Helper method: given a Stream object, and a path relative to that stream path, return a stream for that.

Returns null if no such stream exists, although this function does a lot so throwing is also possible in some cases.

smart_ptr< Stream > nstream::openNamedStream ( IN Manager *  mgr,
IN const char *  name 
)

Helper method: open a Stream for a given path on the specified Manager.

Throws on any error (no entry at that path, entry is not a file, etc.) so the caller is guaranteed a non-NULL return value.

std::string nstream::getStreamName ( IN Stream *  stream  ) 

Helper method: given a Stream, return its name.

eIterationFlag nstream::walkChildFolders ( IN Folder *  root,
IN visit_entry_fn  callback,
IN void *  context,
IN const SetString *  extensions = NULL,
IN const char *  filter = NULL,
IN bool  visitHidden = false 
)

helper methods: given a Folder, walk all child Folders and Entries recursively.

The callback (visit_entry_fn) is called per Entry. If extensions is non-null then only Entries with a name with an extension in the set will be visited. If filter is non-null then only Entries with the filter string somewhere in its path will be visited. Returns the final iteration flag (in other words, will return eIterate_Stop if iteration halted early).

smart_ptr< Manager > nstream::getResourceStreamManager ( void   ) 

get an nstream::Manager that allows clients to explore built-in resources