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