Provided by: ion-doc_3.2.1+dfsg-1.1_all 
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)
perl v5.24.1 2016-07-07 cfdp::doc::pod3::cfdp(3)