Simple library to abstract read-only hierarchies of named streams. More...
|
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:
- a local filesystem. The "name" of each stream is its path, relative to some specific root directory. The hierarchy is the directory structure.
- a remote filesystem, accessed via URL. The "name" of each stream is its URL relative to the server (or a high-level directory of the server). The hierarchy is the URL naming scheme (which often maps to a local filesystem on the server, but doesn't have to).
- a local archive. For instance, a large tar file or a proprietary compressed archiving format. Some object that understands how to parse the compressed archive format will be able to provide named streams, and let clients navigate the archive directory hierarchy.
- and so on (remote compressed archives? a local process? etc.)
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) |
Enumeration Type Documentation
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] |
| 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] |
| 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 | |||
| ) |
| 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
