1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
|
/******************************************************************************
_bei.h: Private header file used to encapsulate structures, constants,
and function prototypes that deal with BP extension blocks.
Author: Scott Burleigh, JPL
Modification History:
Date Who What
Copyright (c) 2010, California Institute of Technology.
ALL RIGHTS RESERVED. U.S. Government Sponsorship acknowledged.
*******************************************************************************/
#ifndef _BEI_H_
#define _BEI_H_
/*****************************************************************************
**
** File Name: _bei.h
**
** Subsystem: BP
**
** Description: This file provides all structures, variables, and function
** definitions necessary to define and manipulate extension
** blocks within the ION BP Agent.
**
** Assumptions:
** 1.
**
** Modification History:
**
** MM/DD/YY AUTHOR IONWG# DESCRIPTION
** -------- ------------ ------- ---------------------------------------
** Original S. Burleigh Initial Implementation
** 04/15/10 E. Birrane 105 Segmented into _bei.h file from bpP.h
*****************************************************************************/
/*****************************************************************************
* FILE INCLUSIONS *
*****************************************************************************/
/*****************************************************************************
* CONSTANT DEFINITIONS *
*****************************************************************************/
/**
* Processing Directives
* These directives identify processing callbacks for areas of the bundle
* protocol agent that handle data flow through parts of the extension
* block lifecycle.
*/
#define PROCESS_ON_FORWARD (0)
#define PROCESS_ON_TAKE_CUSTODY (1)
#define PROCESS_ON_ENQUEUE (2)
#define PROCESS_ON_DEQUEUE (3)
#define PROCESS_ON_TRANSMIT (4)
/*****************************************************************************
* DATA STRUCTURES *
*****************************************************************************/
/**
* \struct ExtensionBlock
* \brief Definition of an SDR-contained Bundle Extension Block.
*
* This structure holds any RFC5050-compliant extension block that is being
* constructed for sending out from the BPA. This structure is stored in the
* SDR and may be persistently stored until the block is ready to be sent and/
* or the containing bundle may be removed.
*/
typedef struct
{
unsigned char rank; /** Order within def array. */
unsigned char type; /** Per definitions array. */
unsigned short blkProcFlags; /** Per BP spec. */
unsigned int dataLength; /** Block content. */
unsigned int length; /** Length of bytes array. */
unsigned int size; /** Size of scratchpad obj. */
Object object; /** Opaque scratchpad. */
Object eidReferences; /** SDR list (may be 0). */
Object bytes; /** Array in SDR heap. */
int suppressed; /** If suppressed. */
} ExtensionBlock;
/**
* \struct AcqExtBlock
* \brief Definition of a memory-only Bundle Extension Block.
*
* This structure holds any RFC5050-compliant extension block that is being
* acquired from an underlying convergence layer. These blocks are stored in
* memory as sent from the personal space manager (PSM).
*/
typedef struct
{
unsigned char type; /** Per extensions array. */
unsigned short blkProcFlags; /** Per BP spec. */
unsigned int dataLength; /** Block content. */
unsigned int length; /** Length of bytes array. */
unsigned int size; /** Size of scratchpad obj. */
void *object; /** Opaque scratchpad. */
Lyst eidReferences; /** May be NULL. */
unsigned char bytes[1]; /** Variable-length array. */
} AcqExtBlock;
/** Functions used on the creation/send side of an extension block. */
typedef int (*BpExtBlkOfferFn)(ExtensionBlock *, Bundle *);
typedef void (*BpExtBlkReleaseFn)(ExtensionBlock *);
typedef int (*BpExtBlkRecordFn)(ExtensionBlock *, AcqExtBlock *);
typedef int (*BpExtBlkCopyFn)(ExtensionBlock *, ExtensionBlock *);
typedef int (*BpExtBlkProcessFn)(ExtensionBlock *, Bundle *, void*);
/** Functions used on the receive side of an extension block. */
typedef int (*BpAcqExtBlkAcquireFn)(AcqExtBlock *, AcqWorkArea *);
typedef int (*BpAcqExtBlkCheckFn)(AcqExtBlock *, AcqWorkArea *);
typedef void (*BpAcqExtBlkClearFn)(AcqExtBlock *);
/**
* \struct ExtensionDef
* \brief Defines the callbacks used to process extension blocks.
*
* ExtensionDefs hold the callbacks, type, and position of the meta-data
* used to define and process extension blocks within the bundle.
*/
typedef struct
{
char name[32]; /** Name of extension */
unsigned char type; /** Block type */
unsigned char listIdx; /** Extension location */
BpExtBlkOfferFn offer; /** Offer */
BpExtBlkReleaseFn release; /** Release */
BpAcqExtBlkAcquireFn acquire; /** Acquire */
BpAcqExtBlkCheckFn check; /** Check */
BpExtBlkRecordFn record; /** Record */
BpAcqExtBlkClearFn clear; /** Clear */
BpExtBlkCopyFn copy; /** Copy */
BpExtBlkProcessFn process[5]; /** ProcessingDirectives*/
} ExtensionDef;
typedef struct
{
unsigned char type; /** The type of correlator block */
unsigned char id; /** Identifier of this block. */
unsigned int size; /** The size of the allocated block. */
} CollabBlockHdr;
/*****************************************************************************
* FUNCTION PROTOTYPES *
*****************************************************************************/
/* Functions that operate on Bundle objects */
extern int addCollaborationBlock(Bundle *bundle, CollabBlockHdr *blkHdr);
extern int attachExtensionBlock(ExtensionDef *def, ExtensionBlock *blk,
Bundle *bundle);
extern int copyCollaborationBlocks(Bundle *newBundle, Bundle *oldBundle);
/**
* \par Function Name: copyExtensionBlock
* \par Purpose:
* \retval int
* \param[out] newBundle The Bundle receiving the copied blocks
* \param[in] oldBundle The Bundle containing the original blocks.
* \par Notes:
* \par Revision History:
* MM/DD/YY AUTHOR IONWG# DESCRIPTION
* -------- ------------ ------ ----------------------------------------
* S. Burleigh Initial Implementation
*/
extern int copyExtensionBlocks(Bundle *newBundle, Bundle *oldBundle);
void deleteExtensionBlock(Object elt, unsigned int listIdx);
void destroyCollaborationBlocks(Bundle *bundle);
void destroyExtensionBlocks(Bundle *bundle);
Object findCollaborationBlock(Bundle *bundle, unsigned char type,
unsigned int id);
/**
* \par Function Name: findExtensionBlock
* \par Purpose:
* \retval Object - The discovered block.
* \param[in] bundle - The bundle holding the desired block.
* \param[in] type - The block identifier desired.
* \param[in] idx - Search before or after the payload.
* \par Notes:
* \par Revision History:
* MM/DD/YY AUTHOR IONWG# DESCRIPTION
* -------- ------------ ------ ----------------------------------------
* S. Burleigh Initial Implementation
*/
extern Object findExtensionBlock(Bundle *bundle, unsigned int type,
unsigned int idx);
extern int insertExtensionBlock(ExtensionDef *def, ExtensionBlock *newBlk,
Object blkAddr, Bundle *bundle, unsigned char listIdx);
extern int patchExtensionBlocks(Bundle *bundle);
extern int processExtensionBlocks(Bundle *bundle, int fnIdx,
void *context);
/**
* \par Function Name: restoreExtensionBlock
* \par Purpose:
* \retval void
* \param[in] blk The block being restored
* \par Notes:
* \par Revision History:
* MM/DD/YY AUTHOR IONWG# DESCRIPTION
* -------- ------------ ------ ----------------------------------------
* S. Burleigh Initial Implementation
*/
extern void restoreExtensionBlock(ExtensionBlock *blk);
/**
* \par Function Name: scratchExtensionBlock
* \par Purpose:
* \retval void
* \param[in] blk The block being scratched.
* \par Notes:
* \par Revision History:
* MM/DD/YY AUTHOR IONWG# DESCRIPTION
* -------- ------------ ------ ----------------------------------------
* S. Burleigh Initial Implementation
*/
extern void scratchExtensionBlock(ExtensionBlock *blk);
/**
* \par Function Name: serializeExtBlk
* \par Purpose:
* \retval void
* \param[in] blk - The block being serialized
* \param[in] eidReferences - EIDs referenced in this block.
* \param[out] blockData - The serialized block.
* \par Notes:
* \par Revision History:
* MM/DD/YY AUTHOR IONWG# DESCRIPTION
* -------- ------------ ------ ----------------------------------------
* S. Burleigh Initial Implementation
*/
extern int serializeExtBlk(ExtensionBlock *blk, Lyst eidReferences,
char *blockData);
/**
* \par Function Name: suppressExtensionBlock
* \par Purpose:
* \retval void
* \param[in] blk The block being suppressed
* \par Notes:
* \par Revision History:
* MM/DD/YY AUTHOR IONWG# DESCRIPTION
* -------- ------------ ------ ----------------------------------------
* S. Burleigh Initial Implementation
*/
extern void suppressExtensionBlock(ExtensionBlock *blk);
extern int updateCollaborationBlock(Object collabAddr,
CollabBlockHdr *blkHdr);
/* Functions that operate on Acquisition Work Area objects */
extern int acquireExtensionBlock(AcqWorkArea *work, ExtensionDef *def,
unsigned char *startOfBlock, unsigned int blockLength,
unsigned char blkType, unsigned int blkProcFlags,
Lyst *eidReferences, unsigned int dataLength);
extern int addAcqCollabBlock(AcqWorkArea *work, CollabBlockHdr *blkHdr);
extern int checkExtensionBlocks(AcqWorkArea *work);
extern void deleteAcqExtBlock(LystElt elt, unsigned int listIdx);
extern void destroyAcqCollabBlocks(AcqWorkArea *work);
/**
* \par Function Name: discardExtensionBlock
* \par Purpose:
* \retval void
* \param[in] blk The block being discarded.
* \par Notes:
* \par Revision History:
* MM/DD/YY AUTHOR IONWG# DESCRIPTION
* -------- ------------ ------ ----------------------------------------
* S. Burleigh Initial Implementation
*/
extern void discardExtensionBlock(AcqExtBlock *blk);
extern LystElt findAcqCollabBlock(AcqWorkArea *work, unsigned char type,
unsigned int id);
extern int recordExtensionBlocks(AcqWorkArea *work);
/* Extension definitions access functions */
extern void getExtensionDefs(ExtensionDef **array, int *count);
extern
ExtensionDef *findExtensionDef(unsigned char type, unsigned char idx);
#endif // _BEI_H_
|
