Main Page   Modules   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members  

SoInput Class Reference

The SoInput class is an abstraction of file import functionality. More...

#include <Inventor/SoInput.h>

List of all members.

Public Methods

 SoInput (void)
 SoInput (SoInput *dictIn)
virtual ~SoInput (void)
virtual void setFilePointer (FILE *newFP)
virtual SbBool openFile (const char *fileName, SbBool okIfNotFound=FALSE)
virtual SbBool pushFile (const char *fileName)
virtual void closeFile (void)
virtual SbBool isValidFile (void)
virtual SbBool isValidBuffer (void)
virtual FILE * getCurFile (void) const
virtual const char * getCurFileName (void) const
virtual void setBuffer (void *bufpointer, size_t bufsize)
virtual size_t getNumBytesRead (void) const
virtual SbString getHeader (void)
virtual float getIVVersion (void)
virtual SbBool isBinary (void)
virtual SbBool get (char &c)
virtual SbBool getASCIIBuffer (char &c)
virtual SbBool getASCIIFile (char &c)
virtual SbBool readHex (uint32_t &l)
virtual SbBool read (char &c)
virtual SbBool read (char &c, SbBool skip)
virtual SbBool read (SbString &s)
virtual SbBool read (SbName &n, SbBool validIdent=FALSE)
virtual SbBool read (int &i)
virtual SbBool read (unsigned int &i)
virtual SbBool read (short &s)
virtual SbBool read (unsigned short &s)
virtual SbBool read (float &f)
virtual SbBool read (double &d)
virtual SbBool readBinaryArray (unsigned char *c, int length)
virtual SbBool readBinaryArray (int32_t *l, int length)
virtual SbBool readBinaryArray (float *f, int length)
virtual SbBool readBinaryArray (double *d, int length)
virtual SbBool eof (void) const
SbBool isFileVRML1 (void)
SbBool isFileVRML2 (void)
virtual void resetFilePointer (FILE *fptr)
virtual void getLocationString (SbString &string) const
virtual void putBack (const char c)
virtual void putBack (const char *str)
virtual void addReference (const SbName &name, SoBase *base, SbBool addToGlobalDict=TRUE)
virtual void removeReference (const SbName &name)
virtual SoBasefindReference (const SbName &name) const

Static Public Methods

void addDirectoryFirst (const char *dirName)
void addDirectoryLast (const char *dirName)
void addEnvDirectoriesFirst (const char *envVarName, const char *separator=":\t")
void addEnvDirectoriesLast (const char *envVarName, const char *separator=":\t")
void removeDirectory (const char *dirName)
void clearDirectories (void)
const SbStringListgetDirectories (void)
void init (void)
SbString getPathname (const char *const filename)
SbString getPathname (const SbString &s)
SbString getBasename (const char *const filename)
SbString getBasename (const SbString &s)
SbString searchForFile (const SbString &basename, const SbStringList &directories, const SbStringList &subdirectories)

Protected Methods

virtual SbBool popFile (void)
void setIVVersion (float version)
FILE * findFile (const char *fileName, SbString &fullName)
void initFile (FILE *newFP, const char *fileName, SbString *fullName, SbBool openedHere, SbDict *refDict=(SbDict *) NULL)
SbBool checkHeader (SbBool bValidateBufferHeader=FALSE)
SbBool fromBuffer (void) const
SbBool skipWhiteSpace (void)
size_t freeBytesInBuf (void) const
SbBool readInteger (int32_t &l)
SbBool readUnsignedInteger (uint32_t &l)
SbBool readReal (double &d)
SbBool readUnsignedIntegerString (char *str)
int readDigits (char *str)
int readHexDigits (char *str)
int readChar (char *str, char charToRead)
SbBool makeRoomInBuf (size_t nBytes)
void convertShort (char *from, short *s)
void convertInt32 (char *from, int32_t *l)
void convertFloat (char *from, float *f)
void convertDouble (char *from, double *d)
void convertShortArray (char *from, short *to, int len)
void convertInt32Array (char *from, int32_t *to, int len)
void convertFloatArray (char *from, float *to, int len)
void convertDoubleArray (char *from, double *to, int len)
SbBool isFileURL (const char *url)
char * URLToFile (char *out_buf, const char *in_buf)
SbBool IsURL (const char *c_strng)

Static Protected Methods

void setDirectories (SbStringList *dirs)


Detailed Description

The SoInput class is an abstraction of file import functionality.

This class takes care of most of the chores of doing data import in Coin. It puts a layer of abstraction over the read operations to make it transparent for the rest of the Coin code whether or not we're reading from a file, from a memory buffer or from stdin.

SoInput also takes care of checking file validity, aswell as handling information about features in the various file formats which are supported.

Example usage:

  int
  main(void)
  {
    SoDB::init();

    SoInput in;
    if (in.openFile("fab_model.iv")) {
      SoSeparator * root = SoDB::readAll(&in);
      if (root) {
        // Do stuff with the imported scene graph here
        // ...
        return 0;
      }
    }

    return 1;
  }

Important note: there are several public and protected methods which makes it possible to pass in or get returned FILE* structures in this class. Do not use these methods when the Coin library has been compiled as an MSWindows DLL, as passing FILE* instances back or forth to DLLs is dangerous and will most likely cause a crash. This is an intrinsic limitation for MSWindows DLLs.

This class supports one environment variable called COIN_SOINPUT_SEARCH_GLOBAL_DICT. When set to "1", the global dictionary is searched after the current file dictionary when resolving USE keywords. This makes it possible to reference nodes in other files. The reason for introducing this feature is that the SoFile node rereads the file whenever the name field changes. The first time the file is read, it's possible to reference nodes in the parent file, using the USE keyword. But, when the file is reread this is no longer possible, since the reading now starts at the SoFile node, with an empty dictionary.

See also:
SoOutput, SoDB


Constructor & Destructor Documentation

SoInput::SoInput void
 

Constructor. If no filepointer is set, input will be read from stdin.

SoInput::SoInput SoInput * dictIn
 

A constructor which copies the reference mappings from dictIn upon initialization.

SoInput::~SoInput void [virtual]
 

Destructor.


Member Function Documentation

void SoInput::setFilePointer FILE * newFP [virtual]
 

Uses the given file pointer as the input file. The input stack of files will be emptied first. Closing a file passed in by it's file pointer is the library user's responsibility.

See also:
openFile(), closeFile()

SbBool SoInput::openFile const char * fileName,
SbBool okIfNotFound = FALSE
[virtual]
 

Open the given file, and make it the only one in the file stack. If okIfNotFound is FALSE, show a warning message if the file could not be opened.

Returns TRUE if file could be opened for reading, FALSE otherwise.

Note: even if your attempt at opening a file is unsuccessful, the SoInput instance will not default to reading from stdin after a call has been made to this method.

See also:
setFilePointer(), pushFile(), closeFile()

SbBool SoInput::pushFile const char * filename [virtual]
 

Push a new file on top of the stack. Further read operations will take place with the new file until it reaches end-of-file, upon when the file will be popped of the stack and we'll continue with the next file in the stack.

Returns TRUE if the file could be opened for reading, FALSE otherwise.

See also:
openFile()

void SoInput::closeFile void [virtual]
 

Removes all files from the internal stack. Any files opened by openFile() or pushFile() will also be closed, but not the files coming from setFilePointer() -- which are the responsibility of the caller.

See also:
setFilePointer(), openFile(), pushFile()

SbBool SoInput::isValidFile void [virtual]
 

Checks to see if the current file is a valid file which can be read by the Coin library.

SbBool SoInput::isValidBuffer void [virtual]
 

Returns TRUE if the current file is a valid file which can be read by the Coin library.

FILE * SoInput::getCurFile void const [virtual]
 

Returns file pointer of the file on top of the input stack. If the "file" is actually a memory buffer, returns NULL.

See also:
getCurFileName()

const char * SoInput::getCurFileName void const [virtual]
 

Returns the name of the file on top of the input stack. NULL will be returned if the toplevel "file" is a memory buffer.

See also:
getCurFile()

void SoInput::setBuffer void * bufpointer,
size_t bufsize
[virtual]
 

Sets up the input stream for reading from a memory buffer. Closes all open files in the file stack first.

size_t SoInput::getNumBytesRead void const [virtual]
 

Returns number of bytes read so far from the current file or memory buffer.

SbString SoInput::getHeader void [virtual]
 

Returns header of current file.

float SoInput::getIVVersion void [virtual]
 

Returns the library version needed to read a file with the given header. If the header of the current file is not valid, this method returns 0.0f.

SbBool SoInput::isBinary void [virtual]
 

Returns TRUE if the current file is in binary format.

SbBool SoInput::get char & c [virtual]
 

Get next character in current stream. Returns FALSE on end of file.

See also:
read()

SbBool SoInput::getASCIIBuffer char & c [virtual]
 

Returns next character in current stream. Don't use this method -- SoInput is supposed to hide whether or not you are reading from file or memory. It is only included for compatibility reasons.

SbBool SoInput::getASCIIFile char & c [virtual]
 

Returns next character in current stream. Don't use this method -- SoInput is supposed to hide whether or not you are reading from file or memory. It is only included for compatibility reasons.

SbBool SoInput::readHex uint32_t & l [virtual]
 

Reads an unsigned integer in hexidecimal format from the current stream. Note that no error checking is done to see if it actually is a hex format value.

A number in hexadecimal format must have the "0x" prefix.

Returns FALSE if end of file is encountered.

SbBool SoInput::read char & c [virtual]
 

Skips whitespace and reads next character in input stream. Returns FALSE if encountering end of file.

SbBool SoInput::read char & c,
SbBool skip
[virtual]
 

Reads next character in input stream, returns FALSE if encountering end of file. If skip is TRUE, skips whitespace before reading a character.

SbBool SoInput::read SbString & s [virtual]
 

Skips whitespace and extracts string. A string can be placed within quotes, in which case we will return all characters between the quotes (including spaces, tabs, newlines, etc). A quote character (i.e. ``"'') can also be part of the string, but must then be preceded by a ``\'' character.

A string not contained in quotes is terminated by the first following whitespace character or left or right bracket (i.e. ``['' or ``]'').

Returns FALSE upon encountering end of file before the string is fully parsed, or any other error.

SbBool SoInput::read SbName & n,
SbBool validIdent = FALSE
[virtual]
 

Read a name from the current stream and place it in n.

If validIdent is TRUE the name needs to be a valid identifier (no reserved characters etc), while validIdent equal to FALSE means we'll just read characters for the next word until we hit whitespace or one of the "{"/"}" delimiters.

Returns FALSE on encountering end of file before a full name has been read -- if validIdent is also FALSE. If validIdent is passed as TRUE, the return value will be FALSE if no valid name was found, but not necessarily on end of file.

SbBool SoInput::read int & i [virtual]
 

Read integer from current file or buffer position and place it in i. Returns FALSE if we hit end of file prematurely.

SbBool SoInput::read unsigned int & i [virtual]
 

Read unsigned integer from current file or buffer position and place it in i. Returns FALSE if we hit end of file prematurely.

SbBool SoInput::read short & s [virtual]
 

Read short integer from current file or buffer position and place it in s. Returns FALSE if we hit end of file prematurely.

SbBool SoInput::read unsigned short & s [virtual]
 

Read unsigned short integer from current file or buffer position and place it in s. Returns FALSE if we hit end of file prematurely.

SbBool SoInput::read float & f [virtual]
 

Read float value from current file or buffer position and place it in f. Returns FALSE if we hit end of file prematurely.

SbBool SoInput::read double & d [virtual]
 

Read double value from current file or buffer position and place it in d. Returns FALSE if we hit end of file prematurely.

SbBool SoInput::readBinaryArray unsigned char * c,
int length
[virtual]
 

Reads length characters from the current stream into c. Returns FALSE if end of file is encountered before the given number of bytes could be read.

SbBool SoInput::readBinaryArray int32_t * l,
int length
[virtual]
 

Reads length 32-bit integers from the current stream into l. Returns FALSE if end of file is encountered before the given number of integers could be read.

SbBool SoInput::readBinaryArray float * f,
int length
[virtual]
 

Reads length floats from the current stream into f. Returns FALSE if end of file is encountered before the given number of binary float values could be read.

SbBool SoInput::readBinaryArray double * d,
int length
[virtual]
 

Reads length double floats from the current stream into d. Returns FALSE if end of file is encountered before the given number of binary double float values could be read.

SbBool SoInput::eof void const [virtual]
 

Returns TRUE if we are at the end of the current stream, otherwise FALSE.

SbBool SoInput::isFileVRML1 void
 

Returns TRUE if current file is a VRML V1.0 file.

This method is an extension versus the Open Inventor API.

SbBool SoInput::isFileVRML2 void
 

Returns TRUE if the current file is in the VRML v2 / VRML97 file format.

void SoInput::resetFilePointer FILE * fptr [virtual]
 

This function has been obsoleted in Coin.

void SoInput::getLocationString SbString & str const [virtual]
 

Places the current line number location and file name in a string which is to be used in the output upon read errors.

void SoInput::putBack const char c [virtual]
 

Insert character c in stream at the current position.

void SoInput::putBack const char * str [virtual]
 

Insert string str in stream at the current position.

void SoInput::addReference const SbName & name,
SoBase * base,
SbBool addToGlobalDict = TRUE
[virtual]
 

Adds a name<->SoBase mapping to our dictionary.

See also:
findReference(), removeReference()

void SoInput::removeReference const SbName & name [virtual]
 

Removes a name<->SoBase mapping from our dictionary.

See also:
findReference(), addReference()

SoBase * SoInput::findReference const SbName & name const [virtual]
 

Finds an SoBase derived object which has been mapped to name earlier during the import process.

See also:
addReference(), removeReference()

void SoInput::addDirectoryFirst const char * dirName [static]
 

Add a directory to the search list. The added directory will be searched before any of the other directories in the list.

See also:
addDirectoryLast(), addEnvDirectoriesFirst(), addEnvDirectoriesLast() , removeDirectory(), clearDirectories()

void SoInput::addDirectoryLast const char * dirName [static]
 

Add a directory to the search list. The added directory will be searched after any of the other directories in the list.

See also:
addDirectoryFirst(), addEnvDirectoriesFirst(), addEnvDirectoriesLast() , removeDirectory(), clearDirectories()

void SoInput::addEnvDirectoriesFirst const char * envVarName,
const char * separator = ":\t "
[static]
 

Add in front of the list all directories in the environment variable envVarName. The separator string should contain all characters to be interpreted as separators in the environment variable string list. The default separators are ':', tab and space.

See also:
addDirectoryFirst(), addDirectoryLast() , addEnvDirectoriesLast() , removeDirectory(), clearDirectories()

void SoInput::addEnvDirectoriesLast const char * envVarName,
const char * separator = ":\t "
[static]
 

Add at the end of the list all directories in the environment variable envVarName. The separator string should contain all characters to be interpreted as separators in the environment variable string list. The default separators are ':', tab and space.

See also:
addDirectoryFirst(), addDirectoryLast() , addEnvDirectoriesFirst() , removeDirectory(), clearDirectories()

void SoInput::removeDirectory const char * dirName [static]
 

Remove the given directory from the directory search list.

The search list is scanned from last to first for the directory name, so directories can easily be "stacked" by pushing with addDirectoryLast() and then removed with this method.

See also:
addDirectoryFirst(), addDirectoryLast() , addEnvDirectoriesFirst(), addEnvDirectoriesLast() , clearDirectories()

void SoInput::clearDirectories void [static]
 

Remove all entries from the directory search list.

See also:
addDirectoryFirst(), addDirectoryLast() , addEnvDirectoriesFirst(), addEnvDirectoriesLast() , removeDirectory()

const SbStringList & SoInput::getDirectories void [static]
 

Returns the list of directories which'll be searched upon loading Coin and VRML format files. Directory searches will be done whenever any external references appears in a file, for instance to texture images.

void SoInput::init void [static]
 

Initialize static variables in class. Called from SoDB::init().

SbString SoInput::getPathname const char *const filename [static]
 

Finds and returns the part of the given filename which is the directory path name.

SbString SoInput::getPathname const SbString & s [static]
 

Finds and returns the part of the given filename which is the directory path name.

SbString SoInput::getBasename const char *const filename [static]
 

Finds and returns the part of the given filename which is the base name (i.e. the filename without the leading directory path).

SbString SoInput::getBasename const SbString & s [static]
 

Finds and returns the part of the given filename which is the base name (i.e. the filename without the leading directory path).

SbString SoInput::searchForFile const SbString & basename,
const SbStringList & directories,
const SbStringList & subdirectories
[static]
 

Given a basename for a file and an array of directories to search, returns the full name of the file found.

In addition to looking at the root of each directory in directories, all subdirectories is also searched for each item in directories.

If no file matching basename could be found in any of the directories, returns an empty string.

This method is a Coin extension, not part of the original Inventor API.

SbBool SoInput::popFile void [protected, virtual]
 

Pop the topmost file off the stack. Returns FALSE if there was no files on the stack to pop.

See also:
pushFile(), openFile(), closeFile()

void SoInput::setIVVersion float version [protected]
 

Changes the file format version number for the stream at the top of the stack.

FILE * SoInput::findFile const char * basename,
SbString & fullname
[protected]
 

Scan through the include directories in order and try to find a file with the given name in any one of them. If file is found, put the full name with complete path from current directory of process into fullname, open the file and return the file pointer.

If the file could either not be found or not opened for reading, return NULL.

void SoInput::initFile FILE * newFP,
const char * fileName,
SbString * fullName,
SbBool openedHere,
SbDict * refDict = (SbDict *) NULL
[protected]
 

This function has been obsoleted in Coin.

SbBool SoInput::checkHeader SbBool bValidateBufferHeader = FALSE [protected]
 

Returns TRUE if the current stream has had it's header parsed. If it hasn't, this method will attempt to read the header and returns TRUE if it could be done.

If bValidateBufferHeader is TRUE, the returned flag will also be FALSE if the file stream header was not of a supported file format type.

SbBool SoInput::fromBuffer void const [protected]
 

Returns TRUE if the current input stream is fetching data from a memory buffer, or FALSE if the input is from a file.

SbBool SoInput::skipWhiteSpace void [protected]
 

Move file pointer past whitespace in the current file or buffer. Returns FALSE if end of file is encountered.

size_t SoInput::freeBytesInBuf void const [protected]
 

This function has been obsoleted in Coin.

SbBool SoInput::readInteger int32_t & l [protected]
 

Reads 32-bit signed integer value from the current stream. Returns FALSE if we hit end of file prematurely.

SbBool SoInput::readUnsignedInteger uint32_t & l [protected]
 

Reads 32-bit unsigned integer value from the current stream. Returns FALSE if we hit end of file prematurely.

SbBool SoInput::readReal double & d [protected]
 

Reads a double-precision floating point value from the current stream. Returns FALSE if we hit end of file prematurely or if no valid string representing a value could be read.

SbBool SoInput::readUnsignedIntegerString char * str [protected]
 

Reads a set of bytes from the stream making up an unsigned integer and puts them at str.

Returns FALSE if no string representing an unsigned integer could be read.

int SoInput::readDigits char * str [protected]
 

Read decimal base digits from the current input stream into str and returns the number of characters read.

int SoInput::readHexDigits char * str [protected]
 

Read hexadecimal base digits from the current input stream into str and returns the number of characters read.

int SoInput::readChar char * s,
char charToRead
[protected]
 

Reads the next character in stream and compares it to charToRead. Returns 1 on success, 0 on failure. Failure may come from either end of file, or from the next character in the stream being different than charToRead.

SbBool SoInput::makeRoomInBuf size_t nBytes [protected]
 

This function has been obsoleted in Coin.

void SoInput::convertShort char * from,
short * s
[protected]
 

Convert the bytes at from (which must be a short integer in network format (i.e. most significant byte first)) to a short integer in native format which is put at the s pointer.

void SoInput::convertInt32 char * from,
int32_t * l
[protected]
 

Convert the bytes at from (which must be a 32-bit integer in network format (i.e. most significant byte first)) to a 32-bit integer in native format which is put at the l pointer.

void SoInput::convertFloat char * from,
float * f
[protected]
 

Convert the bytes at from (which must be a single-precision floating point number in network format) to a single-precision floating point number in native format which is put at the f pointer.

void SoInput::convertDouble char * from,
double * d
[protected]
 

Convert the bytes at from (which must be a double-precision floating point number in network format) to a double-precision floating point number in native format which is put at the d pointer.

void SoInput::convertShortArray char * from,
short * to,
int len
[protected]
 

Convert a block of short numbers in network format to native format.

See also:
convertShort()

void SoInput::convertInt32Array char * from,
int32_t * to,
int len
[protected]
 

Convert a block of 32-bit integer numbers in network format to native format.

See also:
convertInt32()

void SoInput::convertFloatArray char * from,
float * to,
int len
[protected]
 

Convert a b ock of single-precision floating point numbers in network format to native format.

See also:
convertFloat()

void SoInput::convertDoubleArray char * from,
double * to,
int len
[protected]
 

Convert a block of double-precision floating point numbers in network format to native format.

See also:
convertDouble()

SbBool SoInput::isFileURL const char * url [protected]
 

This function is part of the TGS Inventor API, but is not implemented in Coin.

char * SoInput::URLToFile char * out_buf,
const char * in_buf
[protected]
 

This function is part of the TGS Inventor API, but is not implemented in Coin.

SbBool SoInput::IsURL const char * c_strng [protected]
 

This function is part of the TGS Inventor API, but is not implemented in Coin.

void SoInput::setDirectories SbStringList * dirs [static, protected]
 

Set up the directory search path directly with the list of directories in dirs. Note that "." should be part of the directory list if you want to handle files specified by a relative path.


The documentation for this class was generated from the following files:
Generated at Tue Mar 5 03:31:26 2002 for Coin by doxygen1.2.9 written by Dimitri van Heesch, © 1997-2001