EAList

Class EAList should be used whenever you either deal with more than a few EAs at a time or when you don't know the names of the EAs of a file.

After constructing an EAList with one of the constructors, you can add, change and/or delete members of the collection using one of the functions of IGKeySortedSet. The member functions read(), write() and remove() then interact with (existing) physical files. For examples, see Reading, Writing, and Deleting Lists of Extended Attributes.

Class EAList also has some member functions for special tasks like comparing EAs from different files (see Comparing Extended Attributes) or for dumping and reading EAs in binary form to files (see Dumping Extended Attributes to Files).

You can also convert EALists to multi-valued EAs or set the values of collection members of an EALists with the values found in a multi-valued EA. For details, see the section Multi-Valued Extended Attributes.

Reading, Writing and Deleting List of Extended Attributes

A typical example for manipulating EAs using class EAList:

EAList list;

// read some SEAs

list.add(EA(".SUBJECT"));
list.add(EA(".KEYPHRASES"));
list.add(EA(".COMMENTS"));
list.read("test.dat");

// write result to screen

EAList::Cursor current(list);
forCursor(current) {
   const EA& ea = current.element();
   cout << "Name of EA:  " << ea.name() << endl;
   cout << "Type of EA:  " << ea.typeAsString() << endl;
   cout << "Value of EA: " << IString::x2c(ea.value()) << endl;
}

// remove EAs from one file, add them to another

list.remove("test.dat");  // doesn't change list
list.write("test.new");   // test.new must exist

Constructors

There are five public constructors:

• EAList();
• EAList(const EAList& aList);
• EAList(const IString& basename, const EA& mvEA);
• EAList(const char* pathName);
• EAList(HFILE fileHandle);

The first constructor creates an empty EAList, the second (the copy copy-constructor) creates an EAList from a given one, the third constructor creates an EAList from a multi-valued EA and the last two constructors create EALists and read all EAs from the given pathname or file handle.

The third constructor throws an IInvalidRequest exception if the given EA is not multi-valued or if an EA in the MVEA is not length-preceded. The names of the EAs in the list will be basename.1, basename.2 and so on. The number of digits after the period will be the same for all EAs and will be padded by leading zeros if necessary depending on the total number of EAs in the MVEA.

An object of class EAList can either be constructed with the default constructor:

EAList myList;

This creates an empty EAList. Another way to construct an EAList is from a name and a multi-valued EA (see Multi-Valued Extended Attributes) or from a filename/file handle:

IString myFile = "test.dat";
EAList list(myFile);

The last example is equivalent to:

EAList list;
IString myFile = "test.dat";
list.read(myFile,false);

Creating an EAList from a filename is therefore the same as creating an empty EAList and then reading all EAs from the given file.

A copy constructor is also provided.

Functions to change data-members

setValues() 

Sets the values of the EAs in the list to the values of the EAs contained in the given multi-valued EA. This function throws an IInvalidRequest exception if the EA is not multi-valued or if the number of elements in the list and the number of EAs in the MVEA differ.

EAList& setValues(const EA& mvEA);

Functions for interaction with files

read()

Reads EAs from the given file or directory or from the given file handle. If the second argument is false, all EAs of the file are added to the list, while existing elements are removed. If it is true (the default) only EAs from the list are read (if they exist).

EAList& read(const char* pathName, Boolean onlyEAsFromList=true);
EAList& read(HFILE fileHandle, Boolean onlyEAsFromList=true);

write()

Writes the EAList to the given file or directory. The second argument is a speed hack: it uses the internal representation of the EAList from the last read() or write() operation, instead of converting the list to that internal form. The internal representation reflects only the EAList if the list hasn't been changed since then. A typical use for this parameter is reading all EAs from one file and writing the list to another.

EAList& write(const char* pathName, Boolean useFEA2List=false);
EAList& write(HFILE fileHandle, Boolean useFEA2List=false);

remove()

Deletes EAs from a file or directory or from the given file handle. If the second argument is false, all EAs are deleted, if it is true (the default) only EAs from the given list are deleted. The list is not changed.

EAList& remove(const char* pathName, Boolean onlyEAsFromList=true);
EAList& remove(HFILE fileHandle, Boolean onlyEAsFromList=true);

Operators

operator=() 

Implements the assignment operator.

EAList& operator=(const EAList& eaList);

operator<<() 

This operator dumps the internal representation of an EAList to an ostream-object. The internal representation is valid after any read or write operation. If no internal representation exists, it is created from the list (this is why eaList is not a const reference).

The ostream-object should be open in binary mode. The data can be reconverted to a valid EAList using operator>>(). For examples, see Dumping Extended Attributes to files.

friend ostream& operator<<(ostream& out, EAList& eaList);

operator>>() 

This operator reads the internal representation of an EAList from an istream-object and converts it to a valid EAList. The data should have been written to the file with operator<<(). The istream-object should be open in binary mode. All elements in the EAList are removed before converting the internal representation and are therefore lost. See Dumping Extended Attributes to files for an example.

friend istream& operator>>(istream& in, EAList& eaList);