00001 #ifndef PROTON_TRANSPORT_H 00002 #define PROTON_TRANSPORT_H 1 00003 00004 /* 00005 * 00006 * Licensed to the Apache Software Foundation (ASF) under one 00007 * or more contributor license agreements. See the NOTICE file 00008 * distributed with this work for additional information 00009 * regarding copyright ownership. The ASF licenses this file 00010 * to you under the Apache License, Version 2.0 (the 00011 * "License"); you may not use this file except in compliance 00012 * with the License. You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, 00017 * software distributed under the License is distributed on an 00018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00019 * KIND, either express or implied. See the License for the 00020 * specific language governing permissions and limitations 00021 * under the License. 00022 * 00023 */ 00024 00025 #include <proton/import_export.h> 00026 #include <proton/type_compat.h> 00027 #include <stddef.h> 00028 #include <sys/types.h> 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif 00033 00034 /** 00035 * @file 00036 * 00037 * Transport API for the proton Engine. 00038 * 00039 * @defgroup transport Transport 00040 * @ingroup engine 00041 * @{ 00042 */ 00043 00044 /** 00045 * Holds the trace flags for an AMQP transport. 00046 * 00047 * The trace flags for an AMQP transport control what sort of 00048 * information is logged by an AMQP transport. The following bits can 00049 * be set: 00050 * 00051 * - ::PN_TRACE_OFF 00052 * - ::PN_TRACE_RAW 00053 * - ::PN_TRACE_FRM 00054 * - ::PN_TRACE_DRV 00055 * 00056 */ 00057 typedef int pn_trace_t; 00058 00059 /** 00060 * Callback for customizing logging behaviour. 00061 */ 00062 typedef void (*pn_tracer_t)(pn_transport_t *transport, const char *message); 00063 00064 /** 00065 * Turn logging off entirely. 00066 */ 00067 #define PN_TRACE_OFF (0) 00068 00069 /** 00070 * Log raw binary data into/out of the transport. 00071 */ 00072 #define PN_TRACE_RAW (1) 00073 00074 /** 00075 * Log frames into/out of the transport. 00076 */ 00077 #define PN_TRACE_FRM (2) 00078 00079 /** 00080 * Log driver related events, e.g. initialization, end of stream, etc. 00081 */ 00082 #define PN_TRACE_DRV (4) 00083 00084 /** 00085 * Factory for creating a transport. 00086 * 00087 * A transport is used by a connection to interface with the network. 00088 * There can only be one connection associated with a transport. See 00089 * pn_transport_bind(). 00090 * 00091 * @return pointer to new transport 00092 */ 00093 PN_EXTERN pn_transport_t *pn_transport(void); 00094 00095 /** 00096 * Free a transport object. 00097 * 00098 * When a transport is freed, it is automatically unbound from its 00099 * associated connection. 00100 * 00101 * @param[in] transport a transport object or NULL 00102 */ 00103 PN_EXTERN void pn_transport_free(pn_transport_t *transport); 00104 00105 /** 00106 * Get additional error information associated with the transport. 00107 * 00108 * Whenever a transport operation fails (i.e. returns an error code), 00109 * additional error details can be obtained using this function. The 00110 * error object that is returned may also be used to clear the error 00111 * condition. 00112 * 00113 * The pointer returned by this operation is valid until the 00114 * transport object is freed. 00115 * 00116 * @param[in] transport the transport object 00117 * @return the transport's error object 00118 */ 00119 PN_EXTERN pn_error_t *pn_transport_error(pn_transport_t *transport); 00120 00121 /** 00122 * Binds the transport to an AMQP connection. 00123 * 00124 * @return an error code, or 0 on success 00125 */ 00126 PN_EXTERN int pn_transport_bind(pn_transport_t *transport, pn_connection_t *connection); 00127 00128 /** 00129 * Unbinds a transport from its AMQP connection. 00130 * 00131 * @return an error code, or 0 on success 00132 */ 00133 PN_EXTERN int pn_transport_unbind(pn_transport_t *transport); 00134 00135 /** 00136 * Update a transports trace flags. 00137 * 00138 * The trace flags for a transport control what sort of information is 00139 * logged. See ::pn_trace_t for more details. 00140 * 00141 * @param[in] transport a transport object 00142 * @param[in] trace the trace flags 00143 */ 00144 PN_EXTERN void pn_transport_trace(pn_transport_t *transport, pn_trace_t trace); 00145 00146 /** 00147 * Set the tracing function used by a transport. 00148 * 00149 * The tracing function is called to perform logging. Overriding this 00150 * function allows embedding applications to divert the engine's 00151 * logging to a place of their choice. 00152 * 00153 * @param[in] transport a transport object 00154 * @param[in] tracer the tracing function 00155 */ 00156 PN_EXTERN void pn_transport_set_tracer(pn_transport_t *transport, pn_tracer_t tracer); 00157 00158 /** 00159 * Get the tracning function used by a transport. 00160 * 00161 * @param[in] transport a transport object 00162 * @return the tracing function used by a transport 00163 */ 00164 PN_EXTERN pn_tracer_t pn_transport_get_tracer(pn_transport_t *transport); 00165 00166 /** 00167 * Get the application context that is associated with a transport object. 00168 * 00169 * The application context for a transport may be set using 00170 * ::pn_transport_set_context. 00171 * 00172 * @param[in] transport the transport whose context is to be returned. 00173 * @return the application context for the transport object 00174 */ 00175 PN_EXTERN void *pn_transport_get_context(pn_transport_t *transport); 00176 00177 /** 00178 * Set a new application context for a transport object. 00179 * 00180 * The application context for a transport object may be retrieved using 00181 * ::pn_transport_get_context. 00182 * 00183 * @param[in] transport the transport object 00184 * @param[in] context the application context 00185 */ 00186 PN_EXTERN void pn_transport_set_context(pn_transport_t *transport, void *context); 00187 00188 /** 00189 * Log a message using a transport's logging mechanism. 00190 * 00191 * This can be useful in a debugging context as the log message will 00192 * be prefixed with the transport's identifier. 00193 * 00194 * @param[in] transport a transport object 00195 * @param[in] message the message to be logged 00196 */ 00197 PN_EXTERN void pn_transport_log(pn_transport_t *transport, const char *message); 00198 00199 /** 00200 * Log a printf formatted message using a transport's logging 00201 * mechanism. 00202 * 00203 * This can be useful in a debugging context as the log message will 00204 * be prefixed with the transport's identifier. 00205 * 00206 * @param[in] transport a transport object 00207 * @param[in] fmt the printf formatted message to be logged 00208 */ 00209 PN_EXTERN void pn_transport_logf(pn_transport_t *transport, const char *fmt, ...); 00210 00211 /** 00212 * Get the maximum allowed channel for a transport. 00213 * 00214 * @param[in] transport a transport object 00215 * @return the maximum allowed channel 00216 */ 00217 PN_EXTERN uint16_t pn_transport_get_channel_max(pn_transport_t *transport); 00218 00219 /** 00220 * Set the maximum allowed channel for a transport. 00221 * 00222 * @param[in] transport a transport object 00223 * @param[in] channel_max the maximum allowed channel 00224 */ 00225 PN_EXTERN void pn_transport_set_channel_max(pn_transport_t *transport, uint16_t channel_max); 00226 00227 /** 00228 * Get the maximum allowed channel of a transport's remote peer. 00229 * 00230 * @param[in] transport a transport object 00231 * @return the maximum allowed channel of the transport's remote peer 00232 */ 00233 PN_EXTERN uint16_t pn_transport_remote_channel_max(pn_transport_t *transport); 00234 00235 /** 00236 * Get the maximum frame size of a transport. 00237 * 00238 * @param[in] transport a transport object 00239 * @return the maximum frame size of the transport object 00240 */ 00241 PN_EXTERN uint32_t pn_transport_get_max_frame(pn_transport_t *transport); 00242 00243 /** 00244 * Set the maximum frame size of a transport. 00245 * 00246 * @param[in] transport a transport object 00247 * @param[in] size the maximum frame size for the transport object 00248 */ 00249 PN_EXTERN void pn_transport_set_max_frame(pn_transport_t *transport, uint32_t size); 00250 00251 /** 00252 * Get the maximum frame size of a transport's remote peer. 00253 * 00254 * @param[in] transport a transport object 00255 * @return the maximum frame size of the transport's remote peer 00256 */ 00257 PN_EXTERN uint32_t pn_transport_get_remote_max_frame(pn_transport_t *transport); 00258 00259 /** 00260 * Get the idle timeout for a transport. 00261 * 00262 * A zero idle timeout means heartbeats are disabled. 00263 * 00264 * @param[in] transport a transport object 00265 * @return the transport's idle timeout 00266 */ 00267 PN_EXTERN pn_millis_t pn_transport_get_idle_timeout(pn_transport_t *transport); 00268 00269 /** 00270 * Set the idle timeout for a transport. 00271 * 00272 * A zero idle timeout means heartbeats are disabled. 00273 * 00274 * @param[in] transport a transport object 00275 * @param[in] timeout the idle timeout for the transport object 00276 */ 00277 PN_EXTERN void pn_transport_set_idle_timeout(pn_transport_t *transport, pn_millis_t timeout); 00278 00279 /** 00280 * Get the idle timeout for a transport's remote peer. 00281 * 00282 * A zero idle timeout means heartbeats are disabled. 00283 * 00284 * @param[in] transport a transport object 00285 * @return the idle timeout for the transport's remote peer 00286 */ 00287 PN_EXTERN pn_millis_t pn_transport_get_remote_idle_timeout(pn_transport_t *transport); 00288 00289 /** 00290 * @deprecated 00291 */ 00292 PN_EXTERN ssize_t pn_transport_input(pn_transport_t *transport, const char *bytes, size_t available); 00293 /** 00294 * @deprecated 00295 */ 00296 PN_EXTERN ssize_t pn_transport_output(pn_transport_t *transport, char *bytes, size_t size); 00297 00298 /** 00299 * Get the amount of free space for input following the transport's 00300 * tail pointer. 00301 * 00302 * If the engine is in an exceptional state such as encountering an 00303 * error condition or reaching the end of stream state, a negative 00304 * value will be returned indicating the condition. If an error is 00305 * indicated, futher details can be obtained from 00306 * ::pn_transport_error. Calls to ::pn_transport_process may alter the 00307 * value of this pointer. See ::pn_transport_process for details. 00308 * 00309 * @param[in] transport the transport 00310 * @return the free space in the transport, PN_EOS or error code if < 0 00311 */ 00312 PN_EXTERN ssize_t pn_transport_capacity(pn_transport_t *transport); 00313 00314 /** 00315 * Get the transport's tail pointer. 00316 * 00317 * The amount of free space following this pointer is reported by 00318 * ::pn_transport_capacity. Calls to ::pn_transport_process may alther 00319 * the value of this pointer. See ::pn_transport_process for details. 00320 * 00321 * @param[in] transport the transport 00322 * @return a pointer to the transport's input buffer, NULL if no capacity available. 00323 */ 00324 PN_EXTERN char *pn_transport_tail(pn_transport_t *transport); 00325 00326 /** 00327 * Pushes the supplied bytes into the tail of the transport. 00328 * 00329 * This is equivalent to copying @c size bytes afther the tail pointer 00330 * and then calling ::pn_transport_process with an argument of @c 00331 * size. It is an error to call this with a @c size larger than the 00332 * capacity reported by ::pn_transport_capacity. 00333 * 00334 * @param[in] transport the transport 00335 * @param[in] src the start of the data to push into the transport 00336 * @param[in] size the amount of data to push into the transport 00337 * 00338 * @return 0 on success, or error code if < 0 00339 */ 00340 PN_EXTERN int pn_transport_push(pn_transport_t *transport, const char *src, size_t size); 00341 00342 /** 00343 * Process input data following the tail pointer. 00344 * 00345 * Calling this function will cause the transport to consume @c size 00346 * bytes of input occupying the free space following the tail pointer. 00347 * Calls to this function may change the value of ::pn_transport_tail, 00348 * as well as the amount of free space reported by 00349 * ::pn_transport_capacity. 00350 * 00351 * @param[in] transport the transport 00352 * @param[in] size the amount of data written to the transport's input buffer 00353 * @return 0 on success, or error code if < 0 00354 */ 00355 PN_EXTERN int pn_transport_process(pn_transport_t *transport, size_t size); 00356 00357 /** 00358 * Indicate that the input has reached End Of Stream (EOS). 00359 * 00360 * This tells the transport that no more input will be forthcoming. 00361 * 00362 * @param[in] transport the transport 00363 * @return 0 on success, or error code if < 0 00364 */ 00365 PN_EXTERN int pn_transport_close_tail(pn_transport_t *transport); 00366 00367 /** 00368 * Get the number of pending output bytes following the transport's 00369 * head pointer. 00370 * 00371 * If the engine is in an exceptional state such as encountering an 00372 * error condition or reaching the end of stream state, a negative 00373 * value will be returned indicating the condition. If an error is 00374 * indicated, further details can be obtained from 00375 * ::pn_transport_error. Calls to ::pn_transport_pop may alter the 00376 * value of this pointer. See ::pn_transport_pop for details. 00377 * 00378 * @param[in] transport the transport 00379 * @return the number of pending output bytes, or an error code 00380 */ 00381 PN_EXTERN ssize_t pn_transport_pending(pn_transport_t *transport); 00382 00383 /** 00384 * Get the transport's head pointer. 00385 * 00386 * This pointer references queued output data. The 00387 * ::pn_transport_pending function reports how many bytes of output 00388 * data follow this pointer. Calls to ::pn_transport_pop may alter 00389 * this pointer and any data it references. See ::pn_transport_pop for 00390 * details. 00391 * 00392 * @param[in] transport the transport 00393 * @return a pointer to the transport's output buffer, or NULL if no pending output. 00394 */ 00395 PN_EXTERN const char *pn_transport_head(pn_transport_t *transport); 00396 00397 /** 00398 * Copies @c size bytes from the head of the transport to the @c dst 00399 * pointer. 00400 * 00401 * It is an error to call this with a value of @c size that is greater 00402 * than the value reported by ::pn_transport_pending. 00403 * 00404 * @param[in] transport the transport 00405 * @param[out] dst the destination buffer 00406 * @param[in] size the capacity of the destination buffer 00407 * @return 0 on success, or error code if < 0 00408 */ 00409 PN_EXTERN int pn_transport_peek(pn_transport_t *transport, char *dst, size_t size); 00410 00411 /** 00412 * Removes @c size bytes of output from the pending output queue 00413 * following the transport's head pointer. 00414 * 00415 * Calls to this function may alter the transport's head pointer as 00416 * well as the number of pending bytes reported by 00417 * ::pn_transport_pending. 00418 * 00419 * @param[in] transport the transport 00420 * @param[in] size the number of bytes to remove 00421 */ 00422 PN_EXTERN void pn_transport_pop(pn_transport_t *transport, size_t size); 00423 00424 /** 00425 * Indicate that the output has closed. 00426 * 00427 * This tells the transport that no more output will be popped. 00428 * 00429 * @param[in] transport the transport 00430 * @return 0 on success, or error code if < 0 00431 */ 00432 PN_EXTERN int pn_transport_close_head(pn_transport_t *transport); 00433 00434 /** 00435 * Check if a transport has buffered data. 00436 * 00437 * @param[in] transport a transport object 00438 * @return true if the transport has buffered data, false otherwise 00439 */ 00440 PN_EXTERN bool pn_transport_quiesced(pn_transport_t *transport); 00441 00442 /** 00443 * Check if a transport is closed. 00444 * 00445 * A transport is defined to be closed when both the tail and the head 00446 * are closed. In other words, when both ::pn_transport_capacity() < 0 00447 * and ::pn_transport_pending() < 0. 00448 * 00449 * @param[in] transport a transport object 00450 * @return true if the transport is closed, false otherwise 00451 */ 00452 PN_EXTERN bool pn_transport_closed(pn_transport_t *transport); 00453 00454 /** 00455 * Process any pending transport timer events. 00456 * 00457 * This method should be called after all pending input has been 00458 * processed by the transport (see ::pn_transport_input), and before 00459 * generating output (see ::pn_transport_output). It returns the 00460 * deadline for the next pending timer event, if any are present. 00461 * 00462 * @param[in] transport the transport to process. 00463 * @param[in] now the current time 00464 * 00465 * @return if non-zero, then the expiration time of the next pending timer event for the 00466 * transport. The caller must invoke pn_transport_tick again at least once at or before 00467 * this deadline occurs. 00468 */ 00469 PN_EXTERN pn_timestamp_t pn_transport_tick(pn_transport_t *transport, pn_timestamp_t now); 00470 00471 /** 00472 * Get the number of frames output by a transport. 00473 * 00474 * @param[in] transport a transport object 00475 * @return the number of frames output by the transport 00476 */ 00477 PN_EXTERN uint64_t pn_transport_get_frames_output(const pn_transport_t *transport); 00478 00479 /** 00480 * Get the number of frames input by a transport. 00481 * 00482 * @param[in] transport a transport object 00483 * @return the number of frames input by the transport 00484 */ 00485 PN_EXTERN uint64_t pn_transport_get_frames_input(const pn_transport_t *transport); 00486 00487 #ifdef __cplusplus 00488 } 00489 #endif 00490 00491 /** @} 00492 */ 00493 00494 #endif /* transport.h */