NAME

       cfdp - CCSDS File Delivery Protocol (CFDP) communications library

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.

SEE ALSO

       cfdpadmin(1), cfdprc(5)