SYNOPSIS

#include "cfdp.h"
typedef int (*CfdpReaderFn)(int fd, unsigned int *checksum);
typedef enum
{
CfdpCreateFile = 0,
CfdpDeleteFile,
CfdpRenameFile,
CfdpAppendFile,
CfdpReplaceFile,
CfdpCreateDirectory,
CfdpRemoveDirectory,
CfdpDenyFile,
CfdpDenyDirectory
} CfdpAction;
typedef enum
{
CfdpNoEvent = 0,
CfdpTransactionInd,
CfdpEofSentInd,
CfdpTransactionFinishedInd,
CfdpMetadataRecvInd,
CfdpFileSegmentRecvInd,
CfdpEofRecvInd,
CfdpSuspendedInd,
CfdpResumedInd,
CfdpReportInd,
CfdpFaultInd,
CfdpAbandonedInd
} CfdpEventType;
[see description for available functions]

DESCRIPTION

The cfdp library provides functions enabling application software to use CFDP to send and receive files. It conforms to the Class 1 (Unacknowledged) service class defined in the CFDP Blue Book.

In the ION implementation of CFDP, the CFDP notion of entity ID is taken to be identical to the BP (CBHE) notion of DTN node number.

CFDP entity and transaction numbers may be up to 64 bits in length. For portability to 32-bit machines, these numbers are stored in the CFDP state machine as structures of type CfdpNumber.

To simplify the interface between CFDP the user application without risking storage leaks, the CFDP-ION API uses MetadataList objects. A MetadataList is a specially formatted SDR list of user messages, filestore requests, or filestore responses. During the time that a MetadataList is pending processing via the CFDP API, but is not yet (or is no longer) reachable from any FDU object, a pointer to the list is appended to one of the lists of MetadataList objects in the CFDP non-volatile database. This assures that any unplanned termination of the CFDP daemons won't leave any SDR lists unreachable --- and therefore un-recyclable --- due to the absence of references to those lists. Restarting CFDP automatically purges any unused MetadataLists from the CFDP database. The ``user data'' variable of the MetadataList itself is used to implement this feature: while the list is reachable only from the database root, its user data variable points to the database root list from which it is referenced; while the list is attached to a File Delivery Unit, its user data is null.

By default, CFDP transmits the data in a source file in segments of fixed size. The user application can override this behavior at the time transmission of a file is requested, by supplying a file reader callback function that reads the file --- one byte at a time --- until it detects the end of a ``record'' that has application significance. Each time CFDP calls the reader function, the function must return the length of one such record (which must be no greater than 65535).

When CFDP is used to transmit a file, a 32-bit checksum must be provided in the ``EOF'' PDU to enable the receiver of the file to assure that it was not corrupted in transit. When an application-specific file reader function is supplied, that function is responsible for updating the computed checksum as it reads each byte of the file; a CFDP library function is provided for this purpose.

The return value for each CFDP ``request'' function (put, cancel, suspend, resume, report) is a reference number that enables ``events'' obtained by calling cfdp_get_event() to be matched to the requests that caused them. Events with reference number set to zero are events that were caused by autonomous CFDP activity, e.g., the reception of a file data segment.

int cfdp_attach()

Attaches the application to CFDP functionality on the local computer. Returns 0 on success, -1 on any error.

int cfdp_entity_is_started()

Returns 1 if the local CFDP entity has been started and not yet stopped, 0 otherwise.

void cfdp_detach()

Terminates all access to CFDP functionality on the local computer.

void cfdp_compress_number(CfdpNumber *toNbr, uvast from)

Converts an unsigned vast number into a CfdpNumber structure, e.g., for use when invoking the cfdp_put() function.

void cfdp_decompress_number(uvast toNbr, CfdpNumber *from)

Converts a numeric value in a CfdpNumber structure to an unsigned vast integer.

void cfdp_update_checksum(unsigned char octet, unsigned int *offset, unsigned int *checksum)

For use by an application-specific file reader callback function, which must pass to cfdp_update_checksum() the value of each byte (octet) it reads. offset must be octet's displacement in bytes from the start of the file. The checksum pointer is provided to the reader function by CFDP.

MetadataList cfdp_create_usrmsg_list()

Creates a non-volatile linked list, suitable for containing messages-to-user that are to be presented to cfdp_put().

int cfdp_add_usrmsg(MetadataList list, unsigned char *text, int length)

Appends the indicated message-to-user to list.

int cfdp_get_usrmsg(MetadataList list, unsigned char *textBuf, int *length)

Removes from list the first of the remaining messages-to-user contained in the list and delivers its text and length. When the last message in the list is delivered, destroys the list.

void cfdp_destroy_usrmsg_list(MetadataList *list)

Removes and destroys all messages-to-user in list and destroys the list.

MetadataList cfdp_create_fsreq_list()

Creates a non-volatile linked list, suitable for containing filestore requests that are to be presented to cfdp_put().

int cfdp_add_fsreq(MetadataList list, CfdpAction action, char *firstFileName, char *seconfdFIleName)

Appends the indicated filestore request to list.

int cfdp_get_fsreq(MetadataList list, CfdpAction *action, char *firstFileNameBuf, char *secondFileNameBuf)

Removes from list the first of the remaining filestore requests contained in the list and delivers its action code and file names. When the last request in the list is delivered, destroys the list.

void cfdp_destroy_fsreq_list(MetadataList *list)

Removes and destroys all filestore requests in list and destroys the list.

int cfdp_get_fsresp(MetadataList list, CfdpAction *action, int *status, char *firstFileNameBuf, char *secondFileNameBuf, char *messageBuf)

Removes from list the first of the remaining filestore responses contained in the list and delivers its action code, status, file names, and message. When the last response in the list is delivered, destroys the list.

void cfdp_destroy_fsresp_list(MetadataList *list)

Removes and destroys all filestore responses in list and destroys the list.

int cfdp_read_space_packets(int fd, unsigned int *checksum)

This is a standard ``reader'' function that segments the source file on CCSDS space packet boundaries. Multiple small packets may be aggregated into a single file data segment.

int cfdp_read_text_lines(int fd, unsigned int *checksum)

This is a standard ``reader'' function that segments a source file of text lines on line boundaries.

int cfdp_put(CfdpNumber *destinationEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpTransactionId *transactionId)

Sends the file identified by sourceFileName to the CFDP entity identified by destinationEntityNbr. destinationFileName is used to indicate the name by which the file will be catalogued upon arrival at its final destination; if NULL, the destination file name defaults to sourceFileName. If sourceFileName is NULL, it is assumed that the application is requesting transmission of metadata only (as discussed below) and destinationFileName is ignored. Note that both sourceFileName and destinationFileName are interpreted as path names, i.e., directory paths may be indicated in either or both. The syntax of path names is opaque to CFDP; the syntax of sourceFileName must conform to the path naming syntax of the source entity's file system and the syntax of destinationFileName must conform to the path naming syntax of the destination entity's file system.

The byte array identified by utParms, if non-NULL, is interpreted as transmission control information that is to be passed on to the UT layer. The nominal UT layer for ION's CFDP being Bundle Protocol, the utParms array is normally a pointer to a structure of type BpUtParms; see the bp man page for a discussion of the parameters in that structure.

messagesToUser and filestoreRequests, where non-zero, must be the addresses of non-volatile linked lists (that is, linked lists in ION's SDR database) of CfdpMsgToUser and CfdpFilestoreRequest objects identifying metadata that are intended to accompany the transmitted file. Note that this metadata may accompany a file of zero length (as when sourceFileName is NULL as noted above) --- a transmission of metadata only.

On success, the function populates *transactionID with the source entity ID and the transaction number assigned to this transmission and returns the request number identifying this ``put'' request. The transaction ID may be used to suspend, resume, cancel, or request a report on the progress of this transmission. cfdp_put() returns -1 on any error.

int cfdp_cancel(CfdpTransactionId *transactionId)

Cancels transmission or reception of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, cancellation of a file transmission may have little effect. Returns request number on success, -1 on any error.

int cfdp_suspend(CfdpTransactionId *transactionId)

Suspends transmission of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, suspension of a file transmission may have little effect. Returns request number on success, -1 on any error.

int cfdp_resume(CfdpTransactionId *transactionId)

Resumes transmission of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, resumption of a file transmission may have little effect. Returns request number on success, -1 on any error.

int cfdp_report(CfdpTransactionId *transactionId)

Requests issuance of a report on the transmission or reception progress of the indicated transaction. The report takes the form of a character string that is returned in a CfdpEvent structure; use cfdp_get_event() to receive the event (which may be matched to the request by request number). Returns request number on success, 0 if transaction is unknown, -1 on any error.

int cfdp_get_event(CfdpEventType *type, time_t *time, int *reqNbr, CfdpTransactionId *transactionId, char *sourceFileNameBuf, char *destFileNameBuf, unsigned int *fileSize, MetadataList *messagesToUser, unsigned int *offset, unsigned int *length, CfdpCondition *condition, unsigned int *progress, CfdpFileStatus *fileStatus, CfdpDeliveryCode *deliveryCode, CfdpTransactionId *originatingTransactionId, char *statusReportBuf, MetadataList *filestoreResponses);

Populates return value fields with data from the oldest CFDP event not yet delivered to the application.

cfdp_get_event() always blocks indefinitely until an CFDP processing event is delivered or the function is interrupted by an invocation of cfdp_interrupt().

On application error, returns zero but sets errno to EINVAL. Returns -1 on system failure, zero otherwise.

void cfdp_interrupt()

Interrupts an cfdp_get_event() invocation. This function is designed to be called from a signal handler.

int cfdp_preview(CfdpTransactionId *transactionId, unsigned int offset, int length, char *buffer);

This function is provided to enable the application to get an advance look at the content of a file that CFDP has not yet fully received. Reads length bytes starting at offset bytes from the start of the file that is the destination file of the transaction identified by transactionID, into buffer. On user error (transaction is nonexistent or is outbound, or offset is beyond the end of file) returns 0. On system failure, returns -1. Otherwise returns number of bytes read.

int cfdp_map(CfdpTransactionId *transactionId, unsigned int *extentCount, CfdpExtent *extentsArray);

This function is provided to enable the application to report on the portions of a partially-received file that have been received and written. Lists the received continuous data extents in the destination file of the transaction identified by transactionID. The extents (offset and length) are returned in the elements of extentsArray; the number of extents returned in the array is the total number of continuous extents received so far, or extentCount, whichever is less. The total number of extents received so far is returned as the new value of extentCount. On system failure, returns -1. Otherwise returns 0.