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 <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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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 */