Class: Fei

Version 3.01

This is the main class in the FEI application program interface (API). It's used to

Connect and disconnect from FEI servers for particular file types.
Carry out operations on files, including transfering information about files and

the contents of files.

Return FEI profile objects that are part of a

transaction.

Set options for file transmission, like encrypt file, or replace file if it

already exists locally.

FEI status values are returned by many of the methods in this class. Status values are also part of each profile record associated with a file. The status values that can be returned are:

Commands can be queued until Fei's internal request queue is filled. If any attempt to queue a command returns FEI_ERROR, and errno is set to EAGAIN, that means you can try to re-queue your command later. You might try to get some results from fei first.

An Fei connection is to one file type at a time. See also FeiProfile, FeiMsg, FeiDomain.

For more information on the class, see the header file: Fei.h

int Fei::_notify (const char *localPath, const char *restartFileName,
bool optionToGetFile)

Internal method for implementing notify and liveList methods.

int Fei::acceptTheFile (FeiProfile *fileProfile)

Used after getting a profile object back in a notify session. Tells Fei to get the file named in the profile record. The argument to this method is the notify profile record for the file. The next profile object returned following this call, is the profile object for the file requested. Here's a code fragment that shows how this works:

 fei.notify (myFileType, myRestartFile);
 FeiProfile *profile;
 while (fei.results (delayTime)) {
	  if (shouldGetFile (profile->fileName)) {
			profile = fei.result ();
			fei.acceptTheFile (profile);
	  } else {
			profile = fei.result ();
			fei.rejectTheFile (profile);
	  }
	  if (profile) delete profile;
 }

The result () method in the while loop is associated with the notify session. That's check in some way and then either we get or reject the file. The profile record in the if statement is assoicated with the request to get or reject the file.

Note: This method deletes the profile record supplied as its argument. That's why we were able to reuse the variable profile in the example without first deleting the profile object supplied to acceptTheFile() or rejectTheFile(). We follow a simple rule in all cases: "Profile objects passed back from Fei are managed by the caller. Those passed to Fei are managed by the Fei object."

int Fei::add (const char *feiFileName, void *address, size_t size)

Queue an add file request, where the contents of the file is located in memory. The starting address is supplied as address and the length of the buffer is given as size. Queues a profile record upon completion.

Returns FEI_OK upon success; FEI_WARN if the address is NULL or the size is 0; FEI_ERROR otherwise.

See also subscription, notify.

FeiProfile *Fei::result (long delay)

Once you queue a request to transmit a file or after you start a subscription or notify session, Fei returns a set of results. A result set consist of a profile object for each file acted upon plus a final NULL object. (If your request returns no results, the final NULL object is still returned, so the result set always contains at least one queued object, in this case, just the null object.) You retrieve the profile records in the queue using the member function result, with an optional delay time argument. (The delay time is in seconds.) Each call to result returns one profile record, so to get all the queued profile records, a loop is used like so:

  FeiProfile *profile;
  while (profile = fei.result () != (FeiProfile *)NULL) {
		if (profile->getStatus != FEI_OK) {
			 reportError (profile);
			 delete profile;
			 profile = (FeiProfile *)NULL;
		}
		else
			 doSomething (profile);
		delete profile;
  }

In the example (FeiProfile *)NULL is the value of the NULL profile record marking the end of the result set. We continue to get results until we reach the (FeiProfile *)NULL point, indicating that there are no more profiles associated with our transaction.

Notice that the calling function deletes the profile object. Since Fei has handed the profile object off to the caller, it is the caller's responsibility to reclaim the memory used by the object once it's no longer needed.

Since we did not supply a delay time argument to result, it blocks until the Fei object returns a profile record. This form of calling the method simulates single-threaded, synchronous behavior. If a delay time were supplied,

  long delay = 5; // seconds
  profile = fei.result (delay);
  if (profile != (FeiProfile *)NULL) {
		doSomething (profile);
		delete profile;
  }

result () would have waited up to 5 seconds, and then it would have returned, regardless of whether or not a profile object had been queued. We could then come back later and check again for a result. ('Note:' If you want to check for a result and return immediately no matter what the outcome, use a delay value of 0.)

result () returns either a profile object describing a file or the NULL profile object represented by (FeiProfile *)NULL. Note: you should not attempt to delete the NULL profile record.

See also, transactions, class FeiProfile.

int Fei::setOptions (const int mask)

setOptions () adds the or'ed options specified in the mask to the current options mask. New options affect new commands only. Commands already queued operate under the old options. (Fei.h includes FeiProfile.h, so the values are defined in this context as well.) Valid option values are:

encrypt: Encrypt the file during transmission.
crc: Compute a cyclic redundancy check (CRC) value for the file

during transmission. (The CRC value is part of the file's profile record and can be optained using the FeiProfile member function getCrc ().

compress: Compress the file during transmission.

The next three options determine what an Fei object does when it returns a file to the client and finds an existing file with the same name as the file returned.

feiReplace: Replace the existing file.
feiSkip: Don't replace an existing file.
feiVersion: Append a version number (time stamp actually) to the exiting

file and then write the new file using the file name.

feiReplace, feiSkip and feiVersion, are mutually exclusive. If you attempt to define more than one, the following precedence rule is applied when setting the mask value: feiSkip: feiVersion : feiReplace - with feiSkip having the highest precedence.

setOption () returns the current options mask. Initially, only one option is set, feiSkip. Calling setOption () without an argument, resets the option mask to this initial state. See also addOption, isOption.

Here's an example using the member function setOption ():

  int oldMask = fei.setOption (encrypt | crc | feiReplace);
  doSomething (&fei);
  fei.setOption (oldMask);

int Fei::subscribe (const char *localPath, const char *restartFileName)

Start a subscription session for the file type associated with the connection. Information about each file retrieved is queued as a profile record. Returns FEI_OK upon success, FEI_ERROR otherwise.

If the localPath argument is FEI_IN_MEMORY, the file returned as a buffer associated with the file's profile object. Use the FeiProfile member function getAddress() to get the starting address of the file's contents in this case, and getSize() to get the size of the buffer. Note: The buffer is not NULL terminated because FEI assumes no special characters for a file's contents. The file's contents are deleted when the profile record is deleted unless you first reset the address in the profile object using the member function setAddress ((void *)NULL). In that case, you are responsible for deleting the buffer later on. Use delete and not free to do this.

If a restart file name is supplied, the state of the subscription session is record in a file by that name. You can use the restart() command to restart the session from that state later on with a new Fei object.

See also restart, notify, transactions, result, setOption.

int Fei::transactions (void)

Returns the number of transactions queued and not yet completed. A transaction is removed from the queue once all results associated with the transaction are returned. This member function is used to detect the end of a transaction when multiple results can be returned. In the following example, we get back a lists of files. We continue to check for results as long as the transaction is still queued: ie, until all files are returned. Whenever a file is returned we so something with it. In the mean time, we go off and do something else. transaction always returns immediately. If the transaction queue is empty, 0 is returned, otherwise the number of pending transactions is returned

  fei.get ("file.*", .);
  while (fei.transactions () != 0) {
		while (fei.result (0) != (FeiProfile *)NULL) {
			 if (profile)
				  doSomething (profile);
			 else
				  doSomethingElse ();
		}
  }