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 <bsedos.h>. 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

name()

This function returns the value of the name data-member of the EA.

const IString& name() const;

value()

Returns the value of the value data-member of the given object.

const IString& value() const;

type() ; Returns the value of the type data-member of the given object.

USHORT type() const;

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.

static IString typeAsString(USHORT type);
IString typeAsString() const;

flag()

This function returns the value of the flag data-member of the EA.

BYTE flag() const;

Functions to change data-members

setName()

Sets the name data-member of the given object to name.

EA& setName(const IString& name);

setValue()

Sets the value data-member of the given object to value.

EA& setValue(const IString& value);

setType()

Sets the type data-member of the given object to type. Predefined values for type are defined in <bsedos.h>.

EA& setType(USHORT type);

setFlag()

Sets the flag data-member of the given object. Valid values for flag are 0 and FEA_NEEDEA.

EA& setFlag(BYTE flag);

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

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.

USHORT codePage() const;

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.

USHORT numValues() const;

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");