NAME

cbr - Compressed Bundle Reporting and Custody Transfer library

SYNOPSIS

#include "cbr.h"

[see description for available functions]

DESCRIPTION

The cbr library provides functions enabling application software to use Compressed Bundle Reporting (CBR) and Custody Transfer (CT) features as defined in the CCSDS Orange Book "Compressed Bundle Status Reporting and Custody Signaling" specification.

CBR/CT provides two key capabilities:

Compressed Reporting Signals (CRS): A more efficient alternative to traditional BPv7 status reports, allowing multiple bundle status events to be aggregated into a single administrative message.
Custody Transfer with Compressed Custody Signals (CCS): A mechanism for reliable bundle delivery through hop-by-hop custody transfer, where each node explicitly accepts responsibility for bundle delivery.

Note that functions taking Bundle* parameters are internal APIs called from within libbpP.c. External applications should only use the configuration and query functions that do not require Bundle*.

CONSTANTS

Block and Admin Record Types

CBR_BLOCK_TYPE_CTEB     13   Custody Transfer Extension Block
CBR_BLOCK_TYPE_CREB     14   Compressed Reporting Extension Block
CBR_ADMIN_RECORD_CCS    13   Compressed Custody Signal
CBR_ADMIN_RECORD_CRS    14   Compressed Reporting Signal

Custody Disposition Codes

CBR_CUSTODY_ACCEPTED     1   Custody accepted (positive)
CBR_CUSTODY_REFUSED     -1   Custody refused (negative)

Custody Query Status Results

CBR_CUSTODY_STATUS_NOT_FOUND  0   Bundle not in custody tracking
CBR_CUSTODY_STATUS_PENDING    1   Waiting for CCS from next hop
CBR_CUSTODY_STATUS_RELEASED   2   CCS accepted received, released
CBR_CUSTODY_STATUS_REFUSED    3   CCS refused received

Status Reason Codes (CRS)

CBR_STATUS_RECEIVED          0   Bundle was received
CBR_STATUS_FORWARDED         1   Bundle was forwarded
CBR_STATUS_DELIVERED         2   Bundle was delivered
CBR_STATUS_DELETED           3   Bundle was deleted
CBR_STATUS_CUSTODY_ACCEPTED  4   Custody acceptance (info)
CBR_STATUS_CUSTODY_REFUSED   5   Custody refusal (info)

Retransmission Strategies

CBR_RETX_NONE    0   Manual/command-based (default)
CBR_RETX_TIMER   1   Automatic timer-based
CBR_RETX_SIGNAL  2   Signal-based (on CCS refusal)

DATA STRUCTURES

CbrCustodyInfo

Information about a bundle under custody:

typedef struct {
    char    *destEid;          /* Next custodian EID */
    uvast   seqId;             /* CTEB sequence identifier */
    uvast   seqNum;            /* CTEB sequence number */
    time_t  custodyAccepted;   /* When custody was accepted */
    time_t  lastTransmit;      /* When last transmitted */
    int     retransmitCount;   /* Number of retransmissions */
} CbrCustodyInfo;

CbrStatistics

Statistics counters for CBR/CT operations:

typedef struct {
    unsigned int ccsAcceptSent;     /* CCS acceptance signals sent */
    unsigned int ccsRefuseSent;     /* CCS refusal signals sent */
    unsigned int ccsAcceptRecv;     /* CCS acceptance received */
    unsigned int ccsRefuseRecv;     /* CCS refusal received */
    unsigned int custodyOriginated; /* Bundles originated with custody */
    unsigned int custodyAccepted;   /* Bundles accepted into custody */
    unsigned int custodyReleased;   /* Bundles released from custody */
    unsigned int crsSignalsSent;    /* CRS signals sent */
    unsigned int crsSignalsRecv;    /* CRS signals received */
} CbrStatistics;

FUNCTIONS

int cbr_attach( )

Attaches to the CBR/CT subsystem for worker processes. Called automatically by bp_attach(). Returns 0 on success, -1 on error.
int cbr_getStatistics(Sdr sdr, CbrStatistics *stats)

Retrieves CBR/CT statistics counters into stats. Provides definitive proof that CCS/CRS signals were generated and processed. Returns 0 on success, -1 on error.
int cbr_resetStatistics(Sdr sdr)

Resets all CBR/CT statistics counters to zero. Returns 0 on success, -1 on error.
int cbr_listCustodyBundles(Sdr sdr, CbrCustodyCallback callback, void *userData)

Lists all bundles currently held in custody. For each custody bundle, invokes callback with a CbrCustodyInfo structure and the provided userData. Useful for administrative monitoring and manual retransmission decisions. Returns the number of custody bundles, -1 on error.

The callback function type is:
```
typedef void (*CbrCustodyCallback)(CbrCustodyInfo *info, void *userData);
```

int cbr_getCustodyStatus(Sdr sdr, char *sourceEid, uvast seqId, uvast seqNum)

Queries the custody status of a specific bundle identified by sourceEid, seqId, and seqNum. Returns one of the CBR_CUSTODY_STATUS_* values:

CBR_CUSTODY_STATUS_NOT_FOUND   Bundle not in custody tracking
CBR_CUSTODY_STATUS_PENDING     Waiting for CCS from next hop
CBR_CUSTODY_STATUS_RELEASED    CCS accepted, custody released
CBR_CUSTODY_STATUS_REFUSED     CCS refused received

Returns -1 on error.

int cbr_retransmitBundle(Sdr sdr, char *sourceEid, uvast seqId, uvast seqNum)

Manually triggers retransmission of a custody bundle identified by sourceEid, seqId, and seqNum. Used when retransmission strategy is CBR_RETX_NONE (manual mode). Returns 0 on success, -1 on error or bundle not found.
int cbr_retransmitAllCustody(Sdr sdr, char *destEid)

Manually triggers retransmission of all custody bundles destined for destEid. If destEid is NULL, retransmits all custody bundles. Used when retransmission strategy is CBR_RETX_NONE (manual mode). Returns the number of bundles retransmitted, -1 on error.

int cbr_getCustodyMode(Sdr sdr)

Returns the current custody mode setting:

BP_CUSTODY_NONE       (0)   No custody transfer
BP_CUSTODY_BIBE       (1)   BIBE custody transfer (RFC 9171)
BP_CUSTODY_ORANGEBOOK (2)   Orange Book CBR/CT (CTEB/CCS)