═══ 1. About YEA.H ═══ This reference introduce you to YEA.H, a C++ frame work for extended attributes. Introduction Licence agreement Trade marks Contacting the author Publishing EA classes Limitations ═══ 1.1. Introduction. ═══ Introducing YEA.H - Your Extended Attribute Helper YEA.H is an Object Oriented C++ frame work making it simple for you to support extended attributes in your software. YEA.H is designed to be:  Easy to use as a class library, to immediately gain support for some of the most frequently used extended attributes.  Easy to extend with new extended attributes, or make custom implementations for some of the supported attributes. ═══ 1.2. Licence agreement. ═══ YEAH, its compiled library, source code, and documentation, is licensed to you under the following license agreement. Use or distribution of YEAH constitutes your acceptance of that agreement. YEAH, the compiled library, source code and, documentation, is the copyrighted material of BjФrn Fahller. Under this licence, you may: 1. Redistribute YEAH in any way for and shape, suitable to you as long as the original contents remain unchanged and that the redistribution is free (fees to cover media and transfer costs are allowed.) 2. Use YEAH, in your applications, be they free, shareware, educational or commercial. 3. Write and publish additional classes to YEAH, as long as those additional classes are published with the same licence constraints as YEAH. 4. Make proprietary changes to YEAH, provided you do not redistribute YEAH with those changes. Warranty BECAUSE YEAH IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY LAW. USE YEAH AT YOUR OWN RISK. IN NO EVENT SHALL BJЩRN FAHLLER BE HELD LIABLE FOR ANY DAMAGE DUE TO THE USE, ABUSE, OR INABILITY TO USE, YEAH. ═══ 1.3. Trade Marks. ═══ IBM, Visual Age C++ and Open Class Library are registered trade marks of International Business Machines Inc. C++ is (I think) a registered trademark of Unix Systems Laboratories. ═══ 1.4. Contacting the Author. ═══ If you have questions, suggestions, want to report bugs, include new classes in the base package, or for other reasons would like to get in youch with BjФrn Fahller, he can be reached in the following ways: E-mail: bjorn@algonet.se Mail: BjФrn Fahller SiljansvДgen 35 S-120 55 Пrsta SWEDEN. Phone: +46 8 918297 (evenings CET) Fax: +46 8 918297 (daytime CET) The newsgroup comp.os.os2.programmer.oop will also be monitored for discussions regarding YEA.H, but my newsfeed is very slow, often lagging up to a week, so this is most probably not the best way to get quick responses. ═══ 1.5. Publishing EA classes. ═══ If you want to publish concrete extended attribute classes based on YEA.H, you have 3 choises within the licence agreement. 1. Publish the class on your own, with the same licence constraints as YEA.H, i.e. free of charge and with source code. 2. Publish it as a "contribution" to YEA.H. Future releases of YEA.H will have a "contrib" subdirectory, with such classes. You will be the copyright holder for such a contribution, hold the full responsibility for it, document it as you please. The compiled library file, or object file, will be your responsibility too, and it will not be a part of YEAH.LIB. 3. Publish it as a part of YEAH. The difference between this and the previous, is that the compiled object file will be included in YEAH.LIB, that the documentation will be included in future versions of YEAH.INF, that I want to have a say about the way the class is shaped. You still remain the copyright holder, and hold the full responsibility for your classes. If you have plans for such a class, or a set of such classes, please contact me and tell me of your plans. If some one else is also working on a similar class, I will introduce you to each other, so that you may share ideas and, if you so wish, cooperate. For the latter kind, I would specifically like to see an icon class, and a C++ stream based binary class. Bitmap and metafile extended attribute classes would be most welcome too. ═══ 1.6. Limitations. ═══ YEA.H can currently only be used with IBM Visual Age C++, since it makes use of a Visual Age C++ specific #pragma directive ( #pragma define(IKeySortedSet)), which expands the template, regardless of whether it is used in your application or not. Not doing this results in a link error. In the future, this will be removed, since the C++ construct IKeySortedSet; is defined by the proposed ANSI/ISO C++ standard to expand the template. As can be seen, it also makes use of classes IKeySortedSet and IString, which are part of IBM Open Class Library. Once enough parts of the proposed ANSI/ISO C++ standard are commonplace in compilers, a compiler independent version will be written, since the ANSI/ISO C++ standard will include the necessary collection classes and a string class. ═══ 2. Classes ═══ These are the classes available in version 0.9 of YEA.H EA. StringEA. MTSequenceEA. TSequenceEA. TEA. SequenceEA. ═══ 2.1. EA. ═══ EA, Extended Attribute base class. Description. Derivation. Public Interface. Protected Interface. ═══ EA - Description. ═══ EA is the base class for all extended attributes. Most of the use of EA directly is through the many static functions for handling extended attributes in general. Most use of EA, however, will be indirectly, through objects of other classes, implementing concrete extended attributes. ═══ EA - Derivation. ═══ Inherits: none. Inherited by: StringEA (through TEA) MTSequenceEA (through TEA) TSequenceEA (through TEA and SequenceEA) ═══ EA - Public Interface. ═══ Nested types: Identifier Creator CreatorIdPair CreatorMap Flagset Name NameSet Error ErrorHandler Static Public Data. defaultCreatorMap errorHandler Static Public Functions. namesIn newFrom remove Public Instance Functions. Destructor attributeId getFlags setFlags getFrom storeTo clone setCreatorMap ═══ EA - Protected Interface. ═══ Static Protected Functions. read write Instance Protected Functions. Constructors Assignment Operator readFrom writeTo ═══ 2.2. StringEA. ═══ StringEA, String extended attribute (EAT_ASCII). Description. Derivation. Public Interface. Protected Interface. ═══ StringEA - Description. ═══ StringEA represents ASCII string extended attributes used, for example, in the .SUBJECT and .LONGNAME attributes supported by the WPS. To make StringEA easy to use, it inherits IString, and provides the full functionality of IString in addition, of course, to being an extended attribute that can be read and written to files. StringEA implements the EAT_ASCII extended attribute. ═══ StringEA - Derivation. ═══ StringEA is multiply inherited with IString, to provide full string functionality for the extended attribute. ═══ StringEA - Public Interface. ═══ Public Instance Functions Constructors Assignment Operator clone Inherited Public Instance Functions. From EA attributeId getFlags setFlags getFrom storeTo setCreatorMap Public Static Functions - Inherited Public Static Functions. From TEA cast allowDynamic disallowDynamic Class Constants - Inherited Class Constants From TEA id ═══ StringEA - Protected Interface. ═══ Protected Instance Functions readFrom writeTo Inherited Protected Instance Functions - Protected Static Functions - Inherited Protected Static Functions - ═══ 2.3. MTSequenceEA. ═══ MTSequenceEA, Multi Type sequence extended attribute (EAT_MVMT). Description. Derivation. Public Interface. Protected Interface. ═══ MTSequenceEA - Description. ═══ MTSequenceEA represents multi value multi type extended attributes; an extended attribute that is a sequence of other extended attributes. There is no restriction on the types of the contained extended attributes. MTSequenceEA is, for example, used for the .KEYPHRASES, .TYPES and .ASSOCTABLE extended attributes, supported by the WPS. To make MTSequenceEA offer powerful sequence manipulation, yet stay simple to use and consistent with the other sequences in your application, it inherits ISequence. MTSequenceEA implements the EAT_MVMT extended attribute. ═══ MTSequenceEA - Derivation. ═══ MTSequenceEA multiply inherits ISequence, to provide strong sequence manipulation that is easy to use and consistent with the rest of your application. ═══ MTSequenceEA - Public Interface. ═══ Nested Types ErrorFunction Public Instance Data pCreatorMap Public Static Data errorFunction Public Instance Functions Constructors Destructor Assignment Operator clone setCreatorMap getCodePage setCodePage Inherited Instance Public Functions. From EA attributeId getFlags setFlags getFrom storeTo Public Static Functions - Inherited Public Static Functions. From TEA cast allowDynamic disallowDynamic Class Constants - Inherited Class Constants From TEA id ═══ MTSequenceEA - Protected Interface. ═══ Protected Instance Functions readFrom writeTo Inherited Protected Instance Functions - Protected Static Functions - Inherited Protected Static Functions - ═══ 2.4. TSequenceEA. ═══ TSequenceEA, Typed sequence extended attribute (EAT_MVST). Description. Derivation. Public Interface. Protected Interface. ═══ TSequenceEA - Description. ═══ TSequenceEA represents sequences of extended attributes with a common type; in essense, a typed array of extended attributes. TSequenceEA is surpricingly uncommon in OS/2. Even though it could be used for attributes like .KEYPHRASES and .TYPES, they are not. T must be an extended attribute class itself, such as StringEA. IBM Work Frame makes use of string type, typed extended attribute sequences, for storing build support information for make files. TSequenceEA implements the EAT_MVST extended attribute. ═══ TSequenceEA - Derivation. ═══ TSequenceEA multiply inherits ISequence, to provide strong and simple sequence manipulation that is consistent with the rest of your application. ═══ TSequenceEA - Public Interface. ═══ Public Instance Functions Constructors Assignment Operator Destructor clone Inherited Public Instance Functions. From SequenceEA getCodePage setCodePage contentId setCreatorMap From EA attributeId getFlags setFlags getFrom storeTo Static Public Functions. allowDynamic disallowDynamic cast Class Constants. elementId ═══ TSequenceEA - Protected Interface. ═══ Protected Instance Functions readFrom writeTo Inherited Protected Instance Functions - Protected Static Functions - Inherited Protected Static Functions - ═══ 2.5. TEA. ═══ Description. Derivation. Public Interface. Protected Interface. ═══ TEA - Description. ═══ TEA - Intermediate class, providing base functionality for its descendants. You never use this class as is, but it provides a consistent and safe interface to its descendants, at the same time as it saves time for developers of descendants and reduce the risk for errors by removing unecessary code duplication. TEA hides the static member functions namesIn, newFrom and remove from EA, since their use from any class other than directly from EA, would be confusing. EA::newFrom, for example, can return any kind of extended attribute object. If newFrom would be publically available to all descendants of EA, a call to StringEA::newFrom, for example, would be legal, but is in no way guaranteed to return a StringEA object. To avoid the confusion that would arise was the above allowed, the functions are declared private in TEA. For the same reason, the types Creator, CreatorMap, CreatorIdPair, Name,Error, ErrorHandler, Flagset, Identifier and NameSet are hidden by TEA and must be explicitly qualified with EA:: scope when used. ═══ TEA - Derivation. ═══ Inherits. EA Inherited by: StringEA MTSequenceEA SequenceEA ═══ TEA - Public Interface. ═══ Class constants id Public Instance Methods Destructor Public Static Methods cast allowDynamic disallowDynamic ═══ TEA - Protected Interface. ═══ Protected Instance Methods Constructors Assignment Operator ═══ 2.6. SequenceEA. ═══ Description. Derivation. Public Interface. Protected Interface. ═══ SequenceEA - Description. ═══ SequenceEA - Intermediate class, providing common base functionality for TSequenceEA. You should never work directly towards this class, but always towards TSequenceEA. If you want to write your own implementation of typed sequecene extended attributes, SequenceEA can be a good class to inherit from. ═══ SequenceEA - Derivation. ═══ Inherits: EA TEA Inherited by: TSequenceEA ═══ SequenceEA - Public Interface. ═══ Static Public Data. errorFunction Instance Public Functions. Destructor getCodePage setCodePage contentId clone setCreatorMap ═══ SequenceEA - Protected Interface. ═══ Instance Protected Functions. Constructors Assignment Operator writeTo readFrom Instance Protected Data. pCreatorMap Static Protected Functions. allowDynamic ═══ EA::Identifier ═══ typedef unsigned short Identifier; Identifies the type of an extended attribute. Values supported by: OS/2 are: YEA.H are: EAT_BINARY EAT_ASCII StringEA::id EAT_BITMAP EAT_METAFILE EAT_EA EAT_MVMT MTSequenceEA::id EAT_MVST TSequenceEA::id EAT_ASN1 ═══ EA::Creator ═══ typedef EA* (*Creator)(istrstream&, EA::CreatorMap*); Defines a pointer to a function that creates an extended attribute object. For the specific attributes, such functions are defined by the private static member function TEA::createFrom If you write your own creator function, it should read as far into the stream as is needed to know the type of the object to create, and then create the object on the heap. It should not read a value into the object, though. ═══ EA::CreatorIdPair ═══ struct CreatorIdPair { EA::Creator c; EA::Identifier id; IMngPointer pSubMap; } Struct matching an EA::Identifier with an EA::Creator function. Used internally by the EA::newFrom functions, and by multi value extended attributes. The c part is the function that will create new objects on the heap if the element found matches that of id. pSubMap is the map passed to the creator function, which is useful for typed collections, since the creator function will then use that map to create its containing elements. For flat (non-collection extended attributes) pSubMap is 0. ═══ EA::CreatorMap ═══ typedef IMap CreatorMap; Container of EA::CreatorIdPair for use internally by the creator functions, and multi value extended attributes. ═══ EA::Flagset ═══ typedef enum { optional = 0, mandatory = 0x80 } Flagset; Flag used for telling whether an extended attribute is needed (i.e. must not be discarded,) or not. The only legal values are: 0x00 (optional) The extended attribute is not needed. 0x80 (mandatory) The extended attribute is needed. ═══ EA::Name ═══ struct Name { IString name; EA::Flagset flags; }; Description of an extended attribute for a file. A file can be queried for what extended attributes it has, by calling one of the EA::namesIn methods, which returns the set of names as an EA::NameSet, which elements are of type EA::Name. ═══ EA::NameSet ═══ typedef IKeySortedSet NameSet; Set of extended attributes. This is the return value from the EA::namesIn functions. ═══ EA::Error ═══ typedef enum { ReadError, WriteError, NoSuchEAError, TypeMismatchError } Error; The different kinds of errors that can occur within YEA.H. The errors codes are used as follows: Error Situation/Meaning ReadError The extended attribute could not be read. Issued if the file to read from does not exist, or is not readable. The accompanying code sent to the error handler function will be the OS/2 error code. WriteError The extended attribute could not be written. Issued if the file to write to does not exist, is write protected, the extended attribute name was illegal, or the total size of the extended attribute exceeded the 64Kb limit. The accompanying code sent to the error handler function will be the OS/2 error code. NoSuchEAError An attempt was made to read an extended attribute with a name that is not defined for the specified file. The accompanying code sent to the error handler function will be 0. TypeMismatchError An attempt was made to read an extended attribute of a specific type, and the attribute read had another type. The accompanying code sent to te error handler function will be the type identifier of the attribute read. ═══ EA::ErrorHandler ═══ typedef void (*ErrorHandler)(EA::Error, unsigned long); Type of the error handler function. ═══ EA::defaultCreatorMap ═══ public: static EA::CreatorMap defaultCreatorMap; The CreatorMap that will be used for creating extended attribute objects with the getFrom and newFrom functions, unless otherwise specified. ═══ EA::errorHandler ═══ public: static EA::ErrorHandler errorHandler; The ErrorHandler to call when error situations arise. To set your own error handler, simply set this pointer to your own function. The default error handler throws exceptions: Error Exception thrown EA::ReadError EAReadError("Failed to read EA") with the error code given by OS/2 as its errorId. EA::WriteError EAWriteError("Failed to write EA") with the error code given by OS/2 as its errorId. EA::NoSuchEAError EATypeMismatchError("Unknown EA type") with the errorId set to 0. EA::TypeMismatchError EATypeMismatchError("Unexpected EA type") with the type identifier as the errorId. Others. EAError("unknown error"); ═══ EA::namesIn ═══ public: static EA::NameSet namesIn(const IString& file); static EA::NameSet namesIn(fstreambase& file); Get the names for the set of extended attributes defined for the file pointed to by file. Possible errors are: Error Action EA::ReadError EA::errorHandler called with EA::ReadError and the error code given by OS/2. If errorHandler returns, the set returned by namesIn will be empty. ═══ EA::newFrom ═══ public: static EA* newFrom(const IString& file, const IString& name, const EA::CreatorMap& = EA::defaultCreatorMap); static EA* newFrom(fstreambase& file, const IString& name, const EA::CreatorMap& = EA::defaultCreatorMap); Create a new extended attribute object on the heap. The type will be decided when reading the extended attribute, and the object to create will be decided by looking up the creator map passed. Note: To create an object of a class by calling newFrom, the static method allowDynamic must haven been called for the class on the creator map passed. If allowDynamic has not been called, 0 will be returned. Possible errors are: Error Action EA::ReadError Call EA::errorHandler with EA::ReadError and the error code returned by OS/2. EA::errorHandler returns, newFrom returns 0. EA::NoSuchEAError Call EA::errorHandler with EA::NoSuchEAError and 0. If EA::errorHandler returns, newFrom returns 0. Note: In addition to the above, the extended attribute object created can find and report errors of its own. What errors they are, and how they are handled, depends on the type of extended attribute object being created. ═══ EA::remove ═══ public: static void remove(const IString& file, const IString& name); static void remove(fstreambase& file, const IString& name); Remove the extended attribute pointed to by name from the file. After execution, there will be no extended attribute by the specified name on the file, unless an error occurs. Possible errors are: Error Action EA::WriteError Call EA::errorHandler with EA::WriteError and the error code returned by OS/2. ═══ virtual EA::~EA(void) ═══ public: virtual ~EA(void); Destroy an extended attribute. ═══ EA::attributeId ═══ public: EA::Identifier attributeId(void) const; Get the attribute identifier of the extended attribute object. Possible errors are: - ═══ virtual EA::getFlags ═══ public: EA::Flagset getFlags(void) const; Get the flags for the current object. Possible errors are: - ═══ virtual EA::setFlags ═══ public: void setFlags(EA::Flagset); Set the flags for the current object. Possible errors are: - ═══ EA::getFrom ═══ public: void getFrom(const IString& file, const IString& name); void getFrom(fstreambase& file, const IString& name); Give the extended attribute object a new value by assigning it the value read from the named extended attribute. Possible errors are: Error Action EA::ReadError Call EA::errorHandler with EA::ReadError and the error code returned by OS/2. The extended attribute object itself not be changed. EA::NoSuchEAError Call EA::errorHandler with EA::NoSuchEAError and 0. The extended attribute object itself will not be changed. EA::TypeMismatchError Call EA::errorHandler with EA::TypeMismatchError and the type found. The extended attribute object itself will not be changed. Note: If the extended attribute object is a collection extended attribute, the containing parts may themselves find and report other errors. What kind they are of, and how they are reported, depends on the type. ═══ EA::storeTo ═══ public: void storeTo(const IString& file, const IString& name); void storeTo(fstreambase& file, const IString& name); Store the value of the extended attribute to the file, using the name given. Possible errors are: Error Action EA::WriteError Call EA::errorHandler with EA::WriteError and the error code returned by OS/2. ═══ EA::clone ═══ public: virtual EA* clone(void) const = 0; Create an exact deep copy of self. Must be overridden by all descendant classes. Used by the copy constructors and assignment operators of extended attribute collection classes such as MTSequenceEA and TSequenceEA to provide for deep copying. To work properly with typed collection extended attributes, like TSequenceEA the return type must be overridden. The return type for a class C, derived in one or several generations from EA, must be C*. clone will normally not find or report errors, but it depends on the actual extended attribute class if errors can occur, and how they are reported. ═══ EA::setCreatorMap ═══ public: virtual void setCreatorMap(const EA::CreatorMap*) This default implementation of setCreatorMap does nothing at all. Collection classes should override it and create their children from the creator map passed. Possible errors are: - ═══ EA::read ═══ protected: static istrstream& read(EA* pea, istrstream& is) Calls pea->readFrom(is), a way to access the protected method of a sibling. Use when implementing multi value extended attributes, to read a value into one of the attributes contained. read will normally not find or report errors, but it depends on the actual extended attribute class if errors can occur, and how they are reported. Objects of collection extended attribute classes, like MTSequenceEA and TSequenceEA might well find and report errors. ═══ EA::write ═══ protected: static ostrstream& write(EA* pea, ostrstream& os) Calls pea->writeTo(os), a way to access the protected method of a sibling. Use when implementing multi value extended attributes, to save the value of one of the attributes contained. write will normally not find or report errors, but it depends on the actual extended attribute class if errors can occur, and how they are reported. ═══ EA::EA ═══ protected: EA(EA::Identifier anId); EA(const EA&); You would normally not call any of these constructors since TEA does it for you. Would you, however, the identifier to pass is that used to identify the extended attribute (the EA::Identifier part of TEA.) Errors. - ═══ EA::operator= ═══ protected: const EA& operator=(const EA&); You would normally never call the assignment operator of EA, since TEA does it for you. Errors. - ═══ EA::readFrom ═══ protected: virtual istrstream& readFrom(istrstream&) = 0; Must be overridden by all concrete extended attribute classes to read the content of the attribute. Upon entry, the get pointer of the stream is positioned so that the first byte read, will be the byte immediately following the type identifier. This position is not necessarily the first position in the stream. readFrom will normally not find or report errors, but it depends on the actual extended attribute class if errors can occur, and how they are reported. Objects of collection extended attribute classes, like MTSequenceEA and TSequenceEA might well find and report errors. ═══ EA::writeTo ═══ protected: virtual ostrstream& writeTo(ostrstream&) = 0; Must be overridden by all concrete extended attribute classes to write the content of the attribute. Upon entry the type identifier is already written. The first byte to write to the stream is the first byte after the identifier of the type for the extended attribute. writeTo will normally not find or report errors, but it depends on the actual extended attribute class if errors can occur, and how they are reported. ═══ StringEA::StringEA ═══ In addition to all the constructors valid for IString, StringEA supports: public: StringEA(const StringEA& s) Initialise the StringEA object to an exact copy of s. public: StringEA(const IString& filename, const IString& eaname) StringEA(fstreambase& file, const IString& eaname) Constructs a string extended attribute, and reads its value from the extended attribute pointed to bu filename and eaname. Possible errors are: Error Action EA::ReadError Call EA::errorHandler with EA::ReadError and the error code returned by OS/2. If EA::errorHandler returns, an empty StringEA object will be created. EA::NoSuchEAError Call EA::errorHandler with EA::NoSuchEAError and 0. If EA::errorHandler returns, an empty StringEA object will be created. EA::TypeMismatchError Call EA::errorHandler with EA::TypeMismatchError and the type found. If EA::errorHandler returns, an empty StringEA object will be created. For the constructors taking the same arguments as their IString counter parts, the created object will be initialized with with the flag set to EA::optional. ═══ StringEA::operator= ═══ public: const StringEA& operator=(const StringEA& s); Make self an exact copy of s and return self reference. public: const StringEA& operator=(const IString& s); Keep the extended attribute values as is, but assign a new string value to self and return self reference. Possible errors. - ═══ EA::clone ═══ public: virtual StringEA* clone(void) const Create an exact copy of self on the heap and return the pointer to it. Possible errors. - ═══ EA::attributeId ═══ public: EA::Identifier attributeId(void) Returns StringEA::id. Possible errors are: - ═══ EA::getFrom ═══ public: void getFrom(const IString& file, const IString& name); void getFrom(fstreambase& file, const IString& name); Give the string extended attribute object a new value by assigning it the string value read from the named extended attribute. Possible errors are: Error Action EA::ReadError Call EA::errorHandler with EA::ReadError and the error code returned by OS/2. If EA::errorHandler returns, the StringEA object will remain unchanged. EA::NoSuchEAError Call EA::errorHandler with EA::NoSuchEAError and 0. If EA::errorHandler returns, the StringEA object will remain unchanged. EA::TypeMismatchError Call EA::errorHandler with EA::TypeMismatchError and the type found. If EA::errorHandler returns, the StringEA object will remain unchanged. ═══ EA::storeTo ═══ public: void storeTo(const IString& file, const IString& name); void storeTo(fstreambase& file, const IString& name); Store the value of the string extended attribute with the name given. Possible errors are: Error Action EA::WriteError Call EA::errorHandler with EA::WriteError and the error code returned by OS/2. ═══ StringEA::cast ═══ public: static StringEA* cast(EA*) static const StringEA* cast(const EA*) Cast pointers of EA to pointers of StringEA. Return the pointer value if, and only if, attributeId() of the object pointed to returns StringEA::id. Return 0 otherwise. CAUTION: cast is unable to distinguish between StringEA and other implementations of EAT_ASCII, since it compares the attribute id only. Possible errors are: - ═══ StringEA::allowDynamic ═══ public: static void allowDynamic(EA::CreatorMap* pCM = &EA::defaultCreatorMap, const EA::Creator& = TEA::createFrom) Add StringEA to the creator map, making it possible to dynamically create string extended attributes by calling EA::newFrom with that creator map. The StringEA object will be created by a call to the provided creator function. Possible errors. - ═══ StringEA::disallowDynamic ═══ public: static void disallowDynamic(EA::CreatorMap* pCM = &EA::defaultCreatorMap) Remove StringEA from the creator map, making it impossible to dynamically create string extended attributes by calling EA::newFrom with that creator map. Possible errors. - ═══ StringEA::id ═══ public: enum { id = EAT_ASCII }; The identifier of string extended attributes. Use (if you can't avoid it,) to compare with attributeId() of objects. It is usually better not to make that comparison, but to use cast instead, and check the return value of the pointer. ═══ StringEA::readFrom ═══ protected: virtual istrstream& readFrom(istrstream&) Overrides EA::readFrom to read the content of the extended attribute and store its value to the StringEA object itself. Possible errors. - ═══ StringEA::writeTo ═══ protected: virtual ostrstream& writeTo(ostrstream&) Overrides EA::writeTo to store the content of the StringEA object. Possible errors. - ═══ MTSequenceEA::ErrorFunction ═══ public: typedef EA* (*ErrorFunction)(EA::Identifier); The type of the error function called by MTSequenceEA when an extended attribute of unknown type is read. ═══ MTSequenceEA::pCreatorMap ═══ public: EA::CreatorMap* pCreatorMap; Map used by MTSequenceEA when creating the containing extended attributes. It defaults to &EA::defaultCreatorMap. ═══ MTSequenceEA::errorFunction ═══ public: static MTSequenceEA::ErrorFunction errorFunction; Pointer to function, called by MTSequenceEA when reading an extended attribute not found in the creator map. The value returned will be inserted into the sequence. The default function will call EA::errorHandler with TypeMismatchError and the type identifier of the extended attribute read. If EA::errorHandler returns, errorFunction will return 0. To set your own error handler, create a function of type MTSequenceEA::ErrorFunction and set errorFunction to point to it. ═══ MTSequenceEA::MTSequenceEA ═══ public: MTSequenceEA(const EA::CreatorMap* = &EA::defaultCreatorMap); Initialise an empty MTSequenceEA object that creates its contents with the help of the provided creator map. Possible errors. - public: MTSequenceEA(const ISequence&, const EA::CreatorMap* = &EA::defaultCreatorMap); Initialise an MTSequenceEA object by copying the contents of the sequence, and use the creator map provided when reading new values into it. Possible errors. - public: MTSequenceEA(const IString& filename, const IString& eaname, const EA::CreatorMap* = &EA::defaultCreatorMap); MTSequenceEA(fstreambase& file, const IString& eaname, const EA::CreatorMap* = &EA::defaultCreatorMap); Initialise an MTSequenceEA object by reading its contents from the named extended attribute in the selected file, using the provided creator map when creating the containing objects. Possible errors are: Error Action EA::ReadError Call EA::errorHandler with EA::ReadError and the error code returned by OS/2. If EA::errorHandler returns, an empty MTSequenceEA object will be created. EA::NoSuchEAError Call EA::errorHandler with EA::NoSuchEAError and 0. If EA::errorHandler returns, an empty MTSequenceEA object will be created. EA::TypeMismatchError Call EA::errorHandler with EA::TypeMismatchError and the type found. If EA::errorHandler returns, an empty MTSequenceEA object will be created. If an unknown extended attribute is found when reading the content of the sequence, MTSequenceEA::errorFunction is called with the type of the unknown extended attribute. If MTSequenceEA::errorFunction returns, the value returned is inserted into the sequence. public: MTSequenceEA(const MTSequenceEA& mvea); Initialise an MTSequenceEA object by copying the content of the given sequence extended attribute. Possible errors. - ═══ MTSequenceEA::getCodePage ═══ public: unsigned short getCodePage(void) const Return the code page of the MTSequenceEA object. Code page 0 means the default code page of the system. The code page of MTSequenceEA objects defaults to 0. Possible errors. - ═══ MTSequenceEA::setCodePage ═══ public: void setCodePage(unsigned short cp) Set the code page of the MTSequenceEA object. By default, the code page is 0, meaning the default code page of the system. Possible errors. - ═══ EA::attributeId ═══ public: EA::Identifier attributeId(void) Returns MTSequenceEA::id. Possible errors are: - ═══ MTSequenceEA::getFrom ═══ public: void getFrom(const IString& file, const IString& name); void getFrom(fstreambase& file, const IString& name); Give the sequence extended attribute object a new value by assigning it the value read from the named extended attribute. Possible errors are: Error Action EA::ReadError Call EA::errorHandler with EA::ReadError and the error code returned by OS/2. If EA::errorHandler returns, the MTSequenceEA object will remain unchanged. EA::NoSuchEAError Call EA::errorHandler with EA::NoSuchEAError and 0. If EA::errorHandler returns, the MTSequenceEA object will remain unchanged. EA::TypeMismatchError Call EA::errorHandler with EA::TypeMismatchError and the type found. If EA::errorHandler returns, the MTSequenceEA object will remain unchanged. If an unknown extended attribute is found when reading the content of the sequence, MTSequenceEA::errorFunction is called with the type of the unknown extended attribute. If MTSequenceEA::errorFunction returns, the value returned is inserted into the sequence. ═══ MTSequenceEA::storeTo ═══ public: void storeTo(const IString& file, const IString& name); void storeTo(fstreambase& file, const IString& name); Store the value of the sequence extended attribute with the name given. Possible errors are: Error Action EA::WriteError Call EA::errorHandler with EA::WriteError and the error code returned by OS/2. ═══ MTSequenceEA::cast ═══ public: static MTSequenceEA* cast(EA*) static const MTSequenceEA* cast(const EA*) Cast pointers of EA to pointers of MTSequenceEA. Return the pointer value if, and only if, attributeId() of the object pointed to returns MTSequenceEA::id. Return 0 otherwise. CAUTION: cast is unable to distinguish between MTSequenceEA and other implementations of EAT_MVMT, since it compares the attribute id only. Possible errors are: - ═══ MTSequenceEA::allowDynamic ═══ public: static void allowDynamic(EA::CreatorMap* pCM = &EA::defaultCreatorMap, const EA::Creator& creator = TEA::createFrom) Add MTSequenceEA to the creator map, making it possible to dynamically create string extended attributes by calling EA::newFrom with that creator map. The MTSequenceEA object will be created with the provided creator function. Possible errors are: - ═══ MTSequenceEA::disallowDynamic ═══ public: static void disallowDynamic(EA::CreatorMap* pCM = &EA::defaultCreatorMap) Remove MTSequenceEA from the creator map, making it impossible to dynamically create string extended attributes by calling EA::newFrom with that creator map. Possible errors are: - ═══ MTSequenceEA::id ═══ public: enum { id = EAT_MVMT }; The identifier of multi value sequence extended attributes. Use (if you can't avoid it,) to compare with attributeId() of objects. It is usually better not to make that comparison, but to use cast instead, and check the return value of the pointer. ═══ MTSequenceEA::readFrom ═══ protected: virtual istrstream& readFrom(istrstream&) Overrides EA::readFrom to read the content of the extended attribute and store its value to the MTSequenceEA object itself. Possible errors are: Error Action Unknown type read. Calls MTSequenceEA::errorFunction with the type of the unknown extended attribute. If MTSequenceEA::errorFunction returns, the value returned is inserted into the sequence. ═══ MTSequenceEA::writeTo ═══ protected: virtual ostrstream& writeTo(ostrstream&) Overrides EA::writeTo to store the content of the MTSequenceEA object. Possible errors are: - ═══ MTSequenceEA::~MTSequenceEA ═══ public: virtual ~MTSequenceEA(void) Destroys the MTSequenceEA object and deallocates all of its contents. Note: All EA objects pointed to by the MTSequenceEA object by the time of destruction will be deallocated by a call to operator delete. If any of the pointers is not to an object allocated on heap, a run time error is most likely to occur. The reason for this behaviour is to avoid memory leaks if an MTSequenceEA object is read when one is not expected. Possible errors are: - ═══ MTSequenceEA::operator= ═══ In order to make a copy assignment operation work without causing memory leaks, both versions of operator= empties the contents, thus freeing all the pointers in the collection, before the copy. Note: Since operator delete will be executed on all pointers, any pointer referring to an element not allocated on heap is likely to cause a run time error. public: const MTSequenceEA& operator=(const MTSequenceEA& mvea); Make self an exact copy of mvea. The contents of mvea will be cloned to avoid getting several pointers to the same elements, and potential dangling pointers at a later time. Possible errors are: - public: const MTSequenceEA& operator=(const ISequence& isea); Keep the state of self, except for the content of the collection, which is made an exact copy of isea. The contents of isea will be cloned to avoid getting several pointers to the same elements, and potential dangling pointers at a later time. Possible errors are: - ═══ EA::clone ═══ public: virtual MTSequenceEA* clone(void) const; Create an exact deep copy of self on the heap and return the pointer to it. Used by the copy constructors and assignment operators of extended attribute collections such as MTSequenceEA and TSequenceEA. clone itself does not find or report any errors, but since it does a deep copy of the collection, some of its containing objects might. If and how this is done depends on the type of the containig objects. ═══ EA::setCreatorMap ═══ public: virtual void setCreatorMap(const EA::CreatorMap*) Override of the empty default function in EA. It sets the MTSequenceEA::pCreatorMap to the map passed, to make sure children are created from the correct creator map. Possible errors are: - ═══ TSequenceEA::TSequenceEA ═══ public: TSequenceEA(EA::CreatorMap* = &EA::defaultCreatorMap) Initialise a an empty TSequenceEA object. public: TSequenceEA(const TSequenceEA& t) Copy constructor. Initialise a TSequenceEA object by copying the contents and status of t. public: TSequenceEA(const ISequence& t, EA::CreatorMap* = &EA::defaultCreatorMap) Initialise a TSequenceEA object, by copying the contents of the provided ISequence object. public: TSequenceEA(const IString& filename, const IString& eaname, EA::CreatorMap* = &EA::defaultCreatorMap) TSequenceEA(fstreambase& file, const IString& eaname, EA::CreatorMap* = &EA::defaultCreatorMap) Initialise a TSequenceEA object by reading its contents from the named extended attribute of the file. Possible errors are: Error Action EA::ReadError Call EA::errorHandler with EA::ReadError and the error code returned by OS/2. If EA::errorHandler returns, an empty TSequenceEA object will be created. EA::NoSuchEAError Call EA::errorHandler with EA::NoSuchEAError and 0. If EA::errorHandler returns, an empty TSequenceEA object will be created. EA::TypeMismatchError Call EA::errorHandler with EA::TypeMismatchError and the type found. If EA::errorHandler returns, an empty TSequenceEA object will be created. Note: In addition to the above error situations, it is possible that any of the containing objects read into the sequence will find and report errors. If that is done, and how, depends on the type of object read. ═══ TSequenceEA::operator= ═══ To avoid memory leaks, both versions of operator= empty the content of self, and deallocates all pointers, before deep copying the content of the source. Note: Since operator delete will be executed on all pointers, any pointer referring to an element not allocated on heap is likely to cause a run time error. public: const TSequenceEA& operator=(const TSequenceEA& t) Copy the content and status of t to self and return self reference. Possible errors are: - const TSequenceEA& operator=(const ISequence& t) Keep the state of the extended attribute object as is, but assign it new values from the ISequence passed. Possible errors are: - Note: It is possible that some of the contained objects will find and report errors. If that happens, and how, depends on the type of the contained objects. ═══ TSequenceEA::~TSequenceEA ═══ public: virtual ~TSequenceEA(void) Destructor. Note: Unlike the destructor for ISequence, the destructor for TSequenceEA deallocates all pointers to its contents. This is to avoid memory leaks in situations where a TSequenceEA is read when you do not expect one. Warning: If there are extended attribute objects in the sequence that are not allocated on heap, when the destructor is called, a run-time error is very likely to occur since operator delete is called on every pointer in the sequence. Possible errors are: - Note: It is possible that some of the contained objects will find and report errors. If that happens, and how, depends on the type of the contained objects. ═══ TSequenceEA::allowDynamic ═══ public: static void allowDynamic(EA::CreatorMap* pCM = &EA::defaultCreatorMap, const EA::Creator& creator = TSequenceEA::createFrom) Add TSequenceEA to the creator map, making it possible to dynamically create typed sequence extended attributes by calling EA::newFrom with that creator map. The TSequenceEA object will be created by a call to the provided creator function. Possible errors. - ═══ TSequenceEA::disallowDynamic ═══ public: static void disallowDynamic(EA::CreatorMap* pCM = &EA::defaultCreatorMap) Remove the creator of TSequenceEA from the provided creator map, making it impossible to dynamically create TSequenceEA objects from it. Possible errors are: - ═══ TSequenceEA::cast ═══ public: static TSequenceEA* cast(EA*) static const TSequenceEA* cast(const EA*) Cast pointers of EA to pointers of TSequenceEA. Return the pointer value if, and only if, attributeId() of the object equals SequenceEA::id and its contentId() returns T::elementId. Otherwise the value returned will be 0. CAUTION: cast is unable to distinguish between TSequenceEA and other implementations of EAT_MVST, or TSequenceEA where T::id == T2::id for that matter, since only the type identifiers are compared. ═══ TSequenceEA::elementId ═══ template class TSequenceEA ··· { enum { elementId = T::id } Constant for accessing the type identifier of the class that TSequenceEA is parametrised with. For example, TSequenceEA::elementId == StringEA::id. There is little reason to use this constant. It is used internally by TSequenceEA::cast. ═══ EA::clone ═══ public: virtual TSequenceEA* clone(void) const Create an exact deep copy of self on the heap and return the pointer to it. Used by the copy constructors and assignment operators of extended attribute collections such as MTSequenceEA and TSequenceEA. clone itself does not find or report any errors, but since it does a deep copy of the collection, some of the containing objects might. If and how this is done depends on the type of the containig objects. ═══ EA::attributeId ═══ public: EA::Identifier attributeId(void) const Returns SequenceEA::id Possible errors. - ═══ EA::getFrom ═══ public: void getFrom(const IString& file, const IString& name); void getFrom(fstreambase& file, const IString& name); Read the value of the named extended attribute for the file into the TSequenceEA object. Possible errors are: Error Action EA::ReadError Call EA::errorHandler with EA::ReadError and the error code returned by OS/2. If EA::errorHandler returns, the TSequenceEA object will remains unchanged. EA::NoSuchEAError Call EA::errorHandler with EA::NoSuchEAError and 0. If EA::errorHandler returns, the TSequenceEA object will remain unchanged. EA::TypeMismatchError Call EA::errorHandler with EA::TypeMismatchError and the type found. If EA::errorHandler returns, the TSequenceEA object will remain unchanged. TypeMismatchError is called both if the named attribute is not a typed sequence extended attribute, and if the type of the content read is not that of T. Note: In addition to the above, it is possible that some of the contained objects will find and report errors. If and how that is done depends on the type of the objects. ═══ EA::storeTo ═══ public: void storeTo(const IString& file, const IString& name); void storeTo(fstreambase& file, const IString& name); Write the value of the typed extended attribute sequence to the file using the name given. Possible errors are: Error Action EA::WriteError Call EA::errorHandler with EA::WriteError and the error code returned by OS/2. ═══ TSequenceEA::readFrom ═══ protected: virtual istrstream& readFrom(istrstream& is) Overrides EA::readFrom to read the content of the typed sequence extended attribute and store its value in the TSequenceEA Possible errors are: Error Action EA::TypeMismatchError Call EA::errorHandler with EA::TypeMismatchError and the type found. This means that the content type of the sequence (i.e. T::id) was not the content type read from the stream. Note: In addition to the above, it is possible that some of the contained objects will find and report errors. If and how that is done depends on the type of the objects. ═══ TSequenceEA::writeTo ═══ protected: virtual ostrstream& writeTo(ostrstream& os) Overrides EA::writeTo to write the content of the typed sequence extended attribute. Possible errors are: - Note: It is possible that some of the contained objects will find and report errors. If and how that is done depends on the type of the objects. ═══ TEA::id ═══ template class TEA { public: struct { id = eaid; }; ··· A named class constant with the value passed when instantiating TEA. Representing the type for the concrete extended attribute object inheriting from TEA. ═══ TEA::cast ═══ template class TEA { public: static T* cast(EA*); static const T* cast(const EA*); ··· Cast pointers to EA to pointers of class T if, and only if, the type identifier of the EA object is identical to the typeid TEA is instantiated with (i.e. T::id.) Return 0 otherwise. CAUTION: cast is unable to differ between objects of class T and other implementation of T::id, since only the attribute id is compared. Possible errors are: - ═══ TEA::allowDynamic ═══ public: static void allowDynamic(EA::CreatorMap* pCM = &EA::defaultCreatorMap, const EA::Creator& = TEA::createFrom); Add the creator of the descendant of TEA to the provided creator map. Note for designers of new classes A default creator is provided by TEA. If you need a different one, you must write an allowDynamic function for your own class, and a special creator function for it. If you have only a specific creator function, override allowDynamic to take the creator function as its default argument, and call TEA::allowDynamic from your own override. Possible errors are: - ═══ TEA::disallowDynamic ═══ public: static void disallowDynamic(EA::CreatorMap* pCM = &EA::defaultCreatorMap); Remove the creator of the descendant of TEA from the provided creator map. Possible errors are: - ═══ TEA::TEA ═══ protected: TEA(void); TEA(const TEA&t); Initialise the extended attribute base object. Use when implementing descendant extended attribute classes. Possible errors are: - ═══ TEA::operator= ═══ protected: const TEA& operator=(const TEA& t) Copy the content and status of t to self and return self reference. Use in the implementation of descendants from TEA. Possible errors are: - ═══ SequenceEA::errorFunction ═══ public: static EA* (*errorFunction)(EA::Identifier); The error function called if a TSequenceEA, for which allowDynamic has not been called (but another TSequenceEA has been allowed,) is attempted to be read anonymously (by EA::newFrom or as an element in MTSequenceEA) The default function throws an EATSequenceEAInstError exception, with the identifier of the content type as the error code. To override this function, simply assign it your own. The value returned from the function (if it returns) is what EA::newFrom or MTSequenceEA gets. ═══ SequenceEA::~SequenceEA ═══ public: virtual ~SequenceEA(void) Destroy the SequenceEA object. Possible errors are: - ═══ SequenceEA::getCodePage ═══ public: unsigned short getCodePage(void) const; Return the code page used by the TSequenceEA object. Code page 0 means the same code page as used by the application. Possible errors are: - ═══ SequenceEA::setCodePage ═══ public: void setCodePage(unsigned short p) Set the code page for the instance of TSequenceEA. Code page 0 means to use the same code page as the application. Possible errors are: - ═══ SequenceEA::contentId ═══ public: EA::Identifier contentId(void) const Returns the identifier of the content type, i.e. TSequenceEA::contentId() returns T::id. Since you will normally not work with SequenceEA directly, but rather instances of TSequenceEA, there will be little need for this function. It is used internally by the TSequenceEA override of TEA::cast functions. Possible errors are: - ═══ SequenceEA::clone ═══ public: virtual SequenceEA* clone(void) const Returns 0. This version of clone should never be called, since TSequenceEA overrides it. Possible errors are: - ═══ EA::setCreatorMap ═══ public: virtual void setCreatorMap(const EA::CreatorMap*) Override of the empty default function in EA. It sets the SequenceEA::pCreatorMap to the map passed, to make sure children of the TSequenceEA object are created from the correct creator map. Possible errors are: - ═══ SequenceEA::pCreatorMap ═══ protected: const EA::CreatorMap* pCreatorMap Creator map passed to the containing objects of the TSequenceEA inheriting SequenceEA, as they are created, to make sure they are read from the creator map specified. This is only needed if the type of T is a collection class. ═══ SequenceEA::allowDynamic ═══ protected: static void allowDynamic(EA::CreatorMap* pCM, const EA::Creator& creator = SequenceEA::createFrom) Override of the default from TEA, to allow descendants of SequenceEA to allow creation of SequenceEA objects through the private creator function SequenceEA::createFrom. ═══ SequenceEA::SequenceEA ═══ protected: SequenceEA(EA::Identifier id, EA::CreatorMap* pCM = &EA::defaultCreatorMap); SequenceEA(const SequenceEA& mvea); Initialise instance of SequenceEA. Used by the constructors for TSequenceEA. Possible errors are: - ═══ SequenceEA::operator= ═══ protected: const SequenceEA& operator=(const SequenceEA& mvea); Copy content and status of mvea to self and return self reference. Used by the assignment operator in TSequenceEA Possible errors are: - ═══ SequenceEA::writeTo ═══ protected: virtual ostrstream& writeTo(ostrstream& os) Override of EA::writeTo that does nothing. Should never be called since TSequenceEA overrides it. Possible errors are: - ═══ SequenceEA::readFrom ═══ protected: virtual istrstream& readFrom(istrstream& is) Override of EA::readFrom that does nothing. Should never be called since TSequenceEA overrides it. Possible errors are: - ═══ SequenceEA::id ═══ public: enum { id = EAT_MVST }; ═══ ═══ Destructor for TEA. Does nothing explicit, since TEA does not have any data of its own.