EA (class library)

Usage of class EA is straightforward. You create an EA using one of the possible constructors, and then use the object to interact with physical files (see Reading, Writing and Deleting Extended Attributes). The contents of the object can be retrieved and changed by various member functions, see Manipulating EA-Objects).

You should use class EA whenever you know the EAs you are dealing with (by name) and if the number of EAs are small. If you need to read or write a number of EAs to and from a file it is more efficient to use class EAList.

Reading, Writing and Deleting Extend Attributes
To read, write or delete an EA you have to create an appropriate object and then use the correct member function. Note that the member function for deleting an EA from a file is remove (not delete, which is a reserved operator in C++).

The member functions read, write and remove accept either a pathname or a file handle. The file you operate on must exist and must be either open for reading with deny-write mode (if you pass a handle) or must allow opening in the given mode (if you pass a pathname).

Manipulating EA-Objects
Existing EA objects can be changed using the member functions setName, setValue, setType and setFlag.

The data members can be accessed by the member functions name, value, type, typeAsString and flag. typeAsString is also available as a static function.

The member functions numValues and codePage access two fields in the header of multi-valued EAs and throw an exception if the type of the EA is neither EAT_MVMT or EAT_MVST.

Constructors
There are three public constructors: EA(const IString& name,   const void*    buffer,    unsigned long  length,    USHORT         type=EAT_BINARY,    BYTE           flag=0); EA(const IString& name="",   const IString& value="",    BYTE  flag=0); EA(const IString& name,   const EAList&  list,    BYTE  flag=0); The first constructor can be used to construct EAs of any type, the second constructs an EA of type EAT_ASCII and the third converts an EAList to a MV-EA.

Predefined types are defined in . The only valid value for the flag parameter besides 0 is FEA_NEEDEA. In the latter case the EA is marked as critical and only programs explicitly supporting EAs can process the file.

Data-member access functions
const IString& name const; const IString& value const; USHORT type const; static IString typeAsString(USHORT type); IString typeAsString const; BYTE flag const;
 * name : This function returns the value of the name data-member of the EA.
 * value : Returns the value of the value data-member of the given object.
 * type ; Returns the value of the type data-member of the given object.
 * typeAsString : Converts the value of type (resp. the value of the type data-member of the given object) to a string. If the type is not one of the predefined EAT_ types, the functions return "Unknown(xxxx)" were xxxx is the value of the type in hex.
 * flag : This function returns the value of the flag data-member of the EA.

Functions to change data-members
EA& setName(const IString& name); EA& setValue(const IString& value); EA& setType(USHORT type); EA& setFlag(BYTE flag);
 * setName : Sets the name data-member of the given object to name.
 * setValue : Sets the value data-member of the given object to value.
 * setType : Sets the type data-member of the given object to type. Predefined values for type are defined in .
 * setFlag : Sets the flag data-member of the given object. Valid values for flag are 0 and FEA_NEEDEA.

Functions for interaction with files

 * read : Reads the EA with the given name from the file or directory specified by pathName or by fileHandle.

The file must be open or available for read access with deny-write sharing mode.

If the name data-member of the given EA-object is empty, an IInvalidRequest-exception is thrown. EA& read(const char* pathName); EA& read(HFILE fileHandle);


 * write : Write the EA to the file or directory specified by pathName or by fileHandle.

The file must be open or available for write access with deny-read and deny-write sharing mode.

If the name data-member of the given EA-object is empty, an IInvalidRequest-exception is thrown. EA& write(const char* pathName); EA& write(HFILE fileHandle);
 * remove : Deletes the EA with the given name from the file or directory specified by pathName or by fileHandle.

The file must be open or available for write access with deny-read and deny-write sharing mode.

If the name data-member of the given EA-object is empty, an IInvalidRequest-exception is thrown.

The given object is not changed. EA& remove(const char* pathName); EA& remove(HFILE fileHandle);

Functions for multi-valued EAs
USHORT codePage const; USHORT numValues const;
 * codePage: This function returns the codepage field of a MV-EA. If the given EA is not of type EAT_MVST or EAT_MVMT the function throws an IInvalidRequest-exception.
 * numValues: This function returns the number of individual EAs in a MV-EA. If the given EA is not of type EAT_MVST or EAT_MVMT the function throws an IInvalidRequest-exception.

Example Code
Example (assume file test.dat exists, the subject can be set using the settings-notebook of test.dat):  EA sub(".SUBJECT"); sub.read("test.dat"); if (sub.value.length) cout << "Subject of test.dat is " << sub.value << endl: else cout << "test.dat has no subject" << endl; sub.remove("test.dat"); //NB sub does not change! sub.setValue("new subject"); sub.write("test.dat"); 