proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
proton
transport.h
Go to the documentation of this file.
1
#ifndef PROTON_TRANSPORT_H
2
#define PROTON_TRANSPORT_H 1
3
4
/*
5
*
6
* Licensed to the Apache Software Foundation (ASF) under one
7
* or more contributor license agreements. See the NOTICE file
8
* distributed with this work for additional information
9
* regarding copyright ownership. The ASF licenses this file
10
* to you under the Apache License, Version 2.0 (the
11
* "License"); you may not use this file except in compliance
12
* with the License. You may obtain a copy of the License at
13
*
14
* http://www.apache.org/licenses/LICENSE-2.0
15
*
16
* Unless required by applicable law or agreed to in writing,
17
* software distributed under the License is distributed on an
18
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19
* KIND, either express or implied. See the License for the
20
* specific language governing permissions and limitations
21
* under the License.
22
*
23
*/
24
25
#include <
proton/import_export.h
>
26
#include <
proton/type_compat.h
>
27
#include <stddef.h>
28
#include <sys/types.h>
29
30
#ifdef __cplusplus
31
extern
"C"
{
32
#endif
33
34
/**
35
* @file
36
*
37
* Transport API for the proton Engine.
38
*
39
* @defgroup transport Transport
40
* @ingroup engine
41
* @{
42
*/
43
44
/**
45
* Holds the trace flags for an AMQP transport.
46
*
47
* The trace flags for an AMQP transport control what sort of
48
* information is logged by an AMQP transport. The following bits can
49
* be set:
50
*
51
* - ::PN_TRACE_OFF
52
* - ::PN_TRACE_RAW
53
* - ::PN_TRACE_FRM
54
* - ::PN_TRACE_DRV
55
*
56
*/
57
typedef
int
pn_trace_t
;
58
59
/**
60
* Callback for customizing logging behaviour.
61
*/
62
typedef
void (*
pn_tracer_t
)(
pn_transport_t
*transport,
const
char
*message);
63
64
/**
65
* Turn logging off entirely.
66
*/
67
#define PN_TRACE_OFF (0)
68
69
/**
70
* Log raw binary data into/out of the transport.
71
*/
72
#define PN_TRACE_RAW (1)
73
74
/**
75
* Log frames into/out of the transport.
76
*/
77
#define PN_TRACE_FRM (2)
78
79
/**
80
* Log driver related events, e.g. initialization, end of stream, etc.
81
*/
82
#define PN_TRACE_DRV (4)
83
84
/**
85
* Factory for creating a transport.
86
*
87
* A transport is used by a connection to interface with the network.
88
* There can only be one connection associated with a transport. See
89
* pn_transport_bind().
90
*
91
* @return pointer to new transport
92
*/
93
PN_EXTERN
pn_transport_t
*
pn_transport
(
void
);
94
95
/**
96
* Free a transport object.
97
*
98
* When a transport is freed, it is automatically unbound from its
99
* associated connection.
100
*
101
* @param[in] transport a transport object or NULL
102
*/
103
PN_EXTERN
void
pn_transport_free
(
pn_transport_t
*transport);
104
105
/**
106
* Get additional error information associated with the transport.
107
*
108
* Whenever a transport operation fails (i.e. returns an error code),
109
* additional error details can be obtained using this function. The
110
* error object that is returned may also be used to clear the error
111
* condition.
112
*
113
* The pointer returned by this operation is valid until the
114
* transport object is freed.
115
*
116
* @param[in] transport the transport object
117
* @return the transport's error object
118
*/
119
PN_EXTERN
pn_error_t
*
pn_transport_error
(
pn_transport_t
*transport);
120
121
/**
122
* Binds the transport to an AMQP connection.
123
*
124
* @return an error code, or 0 on success
125
*/
126
PN_EXTERN
int
pn_transport_bind
(
pn_transport_t
*transport,
pn_connection_t
*connection);
127
128
/**
129
* Unbinds a transport from its AMQP connection.
130
*
131
* @return an error code, or 0 on success
132
*/
133
PN_EXTERN
int
pn_transport_unbind
(
pn_transport_t
*transport);
134
135
/**
136
* Update a transports trace flags.
137
*
138
* The trace flags for a transport control what sort of information is
139
* logged. See ::pn_trace_t for more details.
140
*
141
* @param[in] transport a transport object
142
* @param[in] trace the trace flags
143
*/
144
PN_EXTERN
void
pn_transport_trace
(
pn_transport_t
*transport, pn_trace_t trace);
145
146
/**
147
* Set the tracing function used by a transport.
148
*
149
* The tracing function is called to perform logging. Overriding this
150
* function allows embedding applications to divert the engine's
151
* logging to a place of their choice.
152
*
153
* @param[in] transport a transport object
154
* @param[in] tracer the tracing function
155
*/
156
PN_EXTERN
void
pn_transport_set_tracer
(
pn_transport_t
*transport,
pn_tracer_t
tracer);
157
158
/**
159
* Get the tracning function used by a transport.
160
*
161
* @param[in] transport a transport object
162
* @return the tracing function used by a transport
163
*/
164
PN_EXTERN
pn_tracer_t
pn_transport_get_tracer
(
pn_transport_t
*transport);
165
166
/**
167
* Get the application context that is associated with a transport object.
168
*
169
* The application context for a transport may be set using
170
* ::pn_transport_set_context.
171
*
172
* @param[in] transport the transport whose context is to be returned.
173
* @return the application context for the transport object
174
*/
175
PN_EXTERN
void
*
pn_transport_get_context
(
pn_transport_t
*transport);
176
177
/**
178
* Set a new application context for a transport object.
179
*
180
* The application context for a transport object may be retrieved using
181
* ::pn_transport_get_context.
182
*
183
* @param[in] transport the transport object
184
* @param[in] context the application context
185
*/
186
PN_EXTERN
void
pn_transport_set_context
(
pn_transport_t
*transport,
void
*context);
187
188
/**
189
* Log a message using a transport's logging mechanism.
190
*
191
* This can be useful in a debugging context as the log message will
192
* be prefixed with the transport's identifier.
193
*
194
* @param[in] transport a transport object
195
* @param[in] message the message to be logged
196
*/
197
PN_EXTERN
void
pn_transport_log
(
pn_transport_t
*transport,
const
char
*message);
198
199
/**
200
* Log a printf formatted message using a transport's logging
201
* mechanism.
202
*
203
* This can be useful in a debugging context as the log message will
204
* be prefixed with the transport's identifier.
205
*
206
* @param[in] transport a transport object
207
* @param[in] fmt the printf formatted message to be logged
208
*/
209
PN_EXTERN
void
pn_transport_logf
(
pn_transport_t
*transport,
const
char
*fmt, ...);
210
211
/**
212
* Get the maximum allowed channel for a transport.
213
*
214
* @param[in] transport a transport object
215
* @return the maximum allowed channel
216
*/
217
PN_EXTERN
uint16_t
pn_transport_get_channel_max
(
pn_transport_t
*transport);
218
219
/**
220
* Set the maximum allowed channel for a transport.
221
*
222
* @param[in] transport a transport object
223
* @param[in] channel_max the maximum allowed channel
224
*/
225
PN_EXTERN
void
pn_transport_set_channel_max
(
pn_transport_t
*transport, uint16_t channel_max);
226
227
/**
228
* Get the maximum allowed channel of a transport's remote peer.
229
*
230
* @param[in] transport a transport object
231
* @return the maximum allowed channel of the transport's remote peer
232
*/
233
PN_EXTERN
uint16_t
pn_transport_remote_channel_max
(
pn_transport_t
*transport);
234
235
/**
236
* Get the maximum frame size of a transport.
237
*
238
* @param[in] transport a transport object
239
* @return the maximum frame size of the transport object
240
*/
241
PN_EXTERN
uint32_t
pn_transport_get_max_frame
(
pn_transport_t
*transport);
242
243
/**
244
* Set the maximum frame size of a transport.
245
*
246
* @param[in] transport a transport object
247
* @param[in] size the maximum frame size for the transport object
248
*/
249
PN_EXTERN
void
pn_transport_set_max_frame
(
pn_transport_t
*transport, uint32_t size);
250
251
/**
252
* Get the maximum frame size of a transport's remote peer.
253
*
254
* @param[in] transport a transport object
255
* @return the maximum frame size of the transport's remote peer
256
*/
257
PN_EXTERN
uint32_t
pn_transport_get_remote_max_frame
(
pn_transport_t
*transport);
258
259
/**
260
* Get the idle timeout for a transport.
261
*
262
* A zero idle timeout means heartbeats are disabled.
263
*
264
* @param[in] transport a transport object
265
* @return the transport's idle timeout
266
*/
267
PN_EXTERN
pn_millis_t
pn_transport_get_idle_timeout
(
pn_transport_t
*transport);
268
269
/**
270
* Set the idle timeout for a transport.
271
*
272
* A zero idle timeout means heartbeats are disabled.
273
*
274
* @param[in] transport a transport object
275
* @param[in] timeout the idle timeout for the transport object
276
*/
277
PN_EXTERN
void
pn_transport_set_idle_timeout
(
pn_transport_t
*transport,
pn_millis_t
timeout);
278
279
/**
280
* Get the idle timeout for a transport's remote peer.
281
*
282
* A zero idle timeout means heartbeats are disabled.
283
*
284
* @param[in] transport a transport object
285
* @return the idle timeout for the transport's remote peer
286
*/
287
PN_EXTERN
pn_millis_t
pn_transport_get_remote_idle_timeout
(
pn_transport_t
*transport);
288
289
/**
290
* @deprecated
291
*/
292
PN_EXTERN
ssize_t
pn_transport_input
(
pn_transport_t
*transport,
const
char
*bytes,
size_t
available);
293
/**
294
* @deprecated
295
*/
296
PN_EXTERN
ssize_t
pn_transport_output
(
pn_transport_t
*transport,
char
*bytes,
size_t
size);
297
298
/**
299
* Get the amount of free space for input following the transport's
300
* tail pointer.
301
*
302
* If the engine is in an exceptional state such as encountering an
303
* error condition or reaching the end of stream state, a negative
304
* value will be returned indicating the condition. If an error is
305
* indicated, futher details can be obtained from
306
* ::pn_transport_error. Calls to ::pn_transport_process may alter the
307
* value of this pointer. See ::pn_transport_process for details.
308
*
309
* @param[in] transport the transport
310
* @return the free space in the transport, PN_EOS or error code if < 0
311
*/
312
PN_EXTERN
ssize_t
pn_transport_capacity
(
pn_transport_t
*transport);
313
314
/**
315
* Get the transport's tail pointer.
316
*
317
* The amount of free space following this pointer is reported by
318
* ::pn_transport_capacity. Calls to ::pn_transport_process may alther
319
* the value of this pointer. See ::pn_transport_process for details.
320
*
321
* @param[in] transport the transport
322
* @return a pointer to the transport's input buffer, NULL if no capacity available.
323
*/
324
PN_EXTERN
char
*
pn_transport_tail
(
pn_transport_t
*transport);
325
326
/**
327
* Pushes the supplied bytes into the tail of the transport.
328
*
329
* This is equivalent to copying @c size bytes afther the tail pointer
330
* and then calling ::pn_transport_process with an argument of @c
331
* size. It is an error to call this with a @c size larger than the
332
* capacity reported by ::pn_transport_capacity.
333
*
334
* @param[in] transport the transport
335
* @param[in] src the start of the data to push into the transport
336
* @param[in] size the amount of data to push into the transport
337
*
338
* @return 0 on success, or error code if < 0
339
*/
340
PN_EXTERN
int
pn_transport_push
(
pn_transport_t
*transport,
const
char
*src,
size_t
size);
341
342
/**
343
* Process input data following the tail pointer.
344
*
345
* Calling this function will cause the transport to consume @c size
346
* bytes of input occupying the free space following the tail pointer.
347
* Calls to this function may change the value of ::pn_transport_tail,
348
* as well as the amount of free space reported by
349
* ::pn_transport_capacity.
350
*
351
* @param[in] transport the transport
352
* @param[in] size the amount of data written to the transport's input buffer
353
* @return 0 on success, or error code if < 0
354
*/
355
PN_EXTERN
int
pn_transport_process
(
pn_transport_t
*transport,
size_t
size);
356
357
/**
358
* Indicate that the input has reached End Of Stream (EOS).
359
*
360
* This tells the transport that no more input will be forthcoming.
361
*
362
* @param[in] transport the transport
363
* @return 0 on success, or error code if < 0
364
*/
365
PN_EXTERN
int
pn_transport_close_tail
(
pn_transport_t
*transport);
366
367
/**
368
* Get the number of pending output bytes following the transport's
369
* head pointer.
370
*
371
* If the engine is in an exceptional state such as encountering an
372
* error condition or reaching the end of stream state, a negative
373
* value will be returned indicating the condition. If an error is
374
* indicated, further details can be obtained from
375
* ::pn_transport_error. Calls to ::pn_transport_pop may alter the
376
* value of this pointer. See ::pn_transport_pop for details.
377
*
378
* @param[in] transport the transport
379
* @return the number of pending output bytes, or an error code
380
*/
381
PN_EXTERN
ssize_t
pn_transport_pending
(
pn_transport_t
*transport);
382
383
/**
384
* Get the transport's head pointer.
385
*
386
* This pointer references queued output data. The
387
* ::pn_transport_pending function reports how many bytes of output
388
* data follow this pointer. Calls to ::pn_transport_pop may alter
389
* this pointer and any data it references. See ::pn_transport_pop for
390
* details.
391
*
392
* @param[in] transport the transport
393
* @return a pointer to the transport's output buffer, or NULL if no pending output.
394
*/
395
PN_EXTERN
const
char
*
pn_transport_head
(
pn_transport_t
*transport);
396
397
/**
398
* Copies @c size bytes from the head of the transport to the @c dst
399
* pointer.
400
*
401
* It is an error to call this with a value of @c size that is greater
402
* than the value reported by ::pn_transport_pending.
403
*
404
* @param[in] transport the transport
405
* @param[out] dst the destination buffer
406
* @param[in] size the capacity of the destination buffer
407
* @return 0 on success, or error code if < 0
408
*/
409
PN_EXTERN
int
pn_transport_peek
(
pn_transport_t
*transport,
char
*dst,
size_t
size);
410
411
/**
412
* Removes @c size bytes of output from the pending output queue
413
* following the transport's head pointer.
414
*
415
* Calls to this function may alter the transport's head pointer as
416
* well as the number of pending bytes reported by
417
* ::pn_transport_pending.
418
*
419
* @param[in] transport the transport
420
* @param[in] size the number of bytes to remove
421
*/
422
PN_EXTERN
void
pn_transport_pop
(
pn_transport_t
*transport,
size_t
size);
423
424
/**
425
* Indicate that the output has closed.
426
*
427
* This tells the transport that no more output will be popped.
428
*
429
* @param[in] transport the transport
430
* @return 0 on success, or error code if < 0
431
*/
432
PN_EXTERN
int
pn_transport_close_head
(
pn_transport_t
*transport);
433
434
/**
435
* Check if a transport has buffered data.
436
*
437
* @param[in] transport a transport object
438
* @return true if the transport has buffered data, false otherwise
439
*/
440
PN_EXTERN
bool
pn_transport_quiesced
(
pn_transport_t
*transport);
441
442
/**
443
* Check if a transport is closed.
444
*
445
* A transport is defined to be closed when both the tail and the head
446
* are closed. In other words, when both ::pn_transport_capacity() < 0
447
* and ::pn_transport_pending() < 0.
448
*
449
* @param[in] transport a transport object
450
* @return true if the transport is closed, false otherwise
451
*/
452
PN_EXTERN
bool
pn_transport_closed
(
pn_transport_t
*transport);
453
454
/**
455
* Process any pending transport timer events.
456
*
457
* This method should be called after all pending input has been
458
* processed by the transport (see ::pn_transport_input), and before
459
* generating output (see ::pn_transport_output). It returns the
460
* deadline for the next pending timer event, if any are present.
461
*
462
* @param[in] transport the transport to process.
463
* @param[in] now the current time
464
*
465
* @return if non-zero, then the expiration time of the next pending timer event for the
466
* transport. The caller must invoke pn_transport_tick again at least once at or before
467
* this deadline occurs.
468
*/
469
PN_EXTERN
pn_timestamp_t
pn_transport_tick
(
pn_transport_t
*transport,
pn_timestamp_t
now);
470
471
/**
472
* Get the number of frames output by a transport.
473
*
474
* @param[in] transport a transport object
475
* @return the number of frames output by the transport
476
*/
477
PN_EXTERN
uint64_t
pn_transport_get_frames_output
(
const
pn_transport_t
*transport);
478
479
/**
480
* Get the number of frames input by a transport.
481
*
482
* @param[in] transport a transport object
483
* @return the number of frames input by the transport
484
*/
485
PN_EXTERN
uint64_t
pn_transport_get_frames_input
(
const
pn_transport_t
*transport);
486
487
#ifdef __cplusplus
488
}
489
#endif
490
491
/** @}
492
*/
493
494
#endif
/* transport.h */
Generated on Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1