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 <proton/condition.h> 00028 #include <stddef.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 * A transport is used by a connection to interface with the network. 00087 * There can only be one connection associated with a transport. See 00088 * pn_transport_bind(). 00089 * 00090 * Initially a transport is configured to be a client transport. Use pn_transport_set_server() 00091 * to configure the transport as a server transport. 00092 * 00093 * A client transport initiates outgoing connections. 00094 * 00095 * A client transport must be configured with the protocol layers to use and cannot 00096 * configure itself automatically. 00097 * 00098 * A server transport accepts incoming connections. It can automatically 00099 * configure itself to include the various protocol layers depending on 00100 * the incoming protocol headers. 00101 * 00102 * @return pointer to new transport 00103 */ 00104 PN_EXTERN pn_transport_t *pn_transport(void); 00105 00106 /** 00107 * Configure a transport as a server 00108 * 00109 * @param[in] transport a transport object 00110 */ 00111 PN_EXTERN void pn_transport_set_server(pn_transport_t *transport); 00112 00113 /** 00114 * Free a transport object. 00115 * 00116 * When a transport is freed, it is automatically unbound from its 00117 * associated connection. 00118 * 00119 * @param[in] transport a transport object or NULL 00120 */ 00121 PN_EXTERN void pn_transport_free(pn_transport_t *transport); 00122 00123 /** Retrieve the authenticated user 00124 * 00125 * This is usually used at the the server end to find the name of the authenticated user. 00126 * On the client it will merely return whatever user was passed in to the 00127 * pn_connection_set_user() API of the bound connection. 00128 * 00129 * The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received. 00130 * 00131 * @param[in] transport the transport 00132 * 00133 * @return 00134 * If a the user is anonymous (either no SASL layer is negotiated or the SASL ANONYMOUS mechanism is used) 00135 * then the user will be "anonymous" 00136 * Otherwise a string containing the user is returned. 00137 */ 00138 PN_EXTERN const char *pn_transport_get_user(pn_transport_t *transport); 00139 00140 /** 00141 * Set whether a non authenticated transport connection is allowed 00142 * 00143 * There are several ways within the AMQP protocol suite to get unauthenticated connections: 00144 * - Use no SASL layer (with either no TLS or TLS without client certificates) 00145 * - Use an SASL layer but the ANONYMOUS mechanism 00146 * 00147 * The default if this option is not set is to allow unauthenticated connections. 00148 * 00149 * @param[in] transport the transport 00150 * @param[in] required boolean is true when authenticated connections are required 00151 */ 00152 PN_EXTERN void pn_transport_require_auth(pn_transport_t *transport, bool required); 00153 00154 /** 00155 * Tell whether the transport connection is authenticated 00156 * 00157 * Note that this property may not be stable until the PN_CONNECTION_REMOTE_OPEN 00158 * event is received. 00159 * 00160 * @param[in] transport the transport 00161 * @return bool representing authentication 00162 */ 00163 PN_EXTERN bool pn_transport_is_authenticated(pn_transport_t *transport); 00164 00165 /** 00166 * Set whether a non encrypted transport connection is allowed 00167 * 00168 * There are several ways within the AMQP protocol suite to get encrypted connections: 00169 * - Use TLS/SSL 00170 * - Use an SASL with a mechanism that supports saecurity layers 00171 * 00172 * The default if this option is not set is to allow unencrypted connections. 00173 * 00174 * @param[in] transport the transport 00175 * @param[in] required boolean is true when encrypted connections are required 00176 */ 00177 PN_EXTERN void pn_transport_require_encryption(pn_transport_t *transport, bool required); 00178 00179 /** 00180 * Tell whether the transport connection is encrypted 00181 * 00182 * Note that this property may not be stable until the PN_CONNECTION_REMOTE_OPEN 00183 * event is received. 00184 * 00185 * @param[in] transport the transport 00186 * @return bool representing encryption 00187 */ 00188 PN_EXTERN bool pn_transport_is_encrypted(pn_transport_t *transport); 00189 00190 /** 00191 * Get additional information about the condition of the transport. 00192 * 00193 * When a PN_TRANSPORT_ERROR event occurs, this operation can be used 00194 * to access the details of the error condtion. 00195 * 00196 * The pointer returned by this operation is valid until the 00197 * transport object is freed. 00198 * 00199 * @param[in] transport the transport object 00200 * @return the transport's condition object 00201 */ 00202 PN_EXTERN pn_condition_t *pn_transport_condition(pn_transport_t *transport); 00203 00204 /** 00205 * @deprecated 00206 */ 00207 PN_EXTERN pn_error_t *pn_transport_error(pn_transport_t *transport); 00208 00209 /** 00210 * Binds the transport to an AMQP connection. 00211 * 00212 * @return an error code, or 0 on success 00213 */ 00214 PN_EXTERN int pn_transport_bind(pn_transport_t *transport, pn_connection_t *connection); 00215 00216 /** 00217 * Unbinds a transport from its AMQP connection. 00218 * 00219 * @return an error code, or 0 on success 00220 */ 00221 PN_EXTERN int pn_transport_unbind(pn_transport_t *transport); 00222 00223 /** 00224 * Update a transports trace flags. 00225 * 00226 * The trace flags for a transport control what sort of information is 00227 * logged. See ::pn_trace_t for more details. 00228 * 00229 * @param[in] transport a transport object 00230 * @param[in] trace the trace flags 00231 */ 00232 PN_EXTERN void pn_transport_trace(pn_transport_t *transport, pn_trace_t trace); 00233 00234 /** 00235 * Set the tracing function used by a transport. 00236 * 00237 * The tracing function is called to perform logging. Overriding this 00238 * function allows embedding applications to divert the engine's 00239 * logging to a place of their choice. 00240 * 00241 * @param[in] transport a transport object 00242 * @param[in] tracer the tracing function 00243 */ 00244 PN_EXTERN void pn_transport_set_tracer(pn_transport_t *transport, pn_tracer_t tracer); 00245 00246 /** 00247 * Get the tracning function used by a transport. 00248 * 00249 * @param[in] transport a transport object 00250 * @return the tracing function used by a transport 00251 */ 00252 PN_EXTERN pn_tracer_t pn_transport_get_tracer(pn_transport_t *transport); 00253 00254 /** 00255 * Get the application context that is associated with a transport object. 00256 * 00257 * The application context for a transport may be set using 00258 * ::pn_transport_set_context. 00259 * 00260 * @param[in] transport the transport whose context is to be returned. 00261 * @return the application context for the transport object 00262 */ 00263 PN_EXTERN void *pn_transport_get_context(pn_transport_t *transport); 00264 00265 /** 00266 * @deprecated 00267 * Set a new application context for a transport object. 00268 * 00269 * The application context for a transport object may be retrieved using 00270 * ::pn_transport_get_context. 00271 * 00272 * @param[in] transport the transport object 00273 * @param[in] context the application context 00274 */ 00275 PN_EXTERN void pn_transport_set_context(pn_transport_t *transport, void *context); 00276 00277 /** 00278 * Get the attachments that are associated with a transport object. 00279 * 00280 * @param[in] transport the transport whose attachments are to be returned. 00281 * @return the attachments for the transport object 00282 */ 00283 PN_EXTERN pn_record_t *pn_transport_attachments(pn_transport_t *transport); 00284 00285 /** 00286 * Log a message using a transport's logging mechanism. 00287 * 00288 * This can be useful in a debugging context as the log message will 00289 * be prefixed with the transport's identifier. 00290 * 00291 * @param[in] transport a transport object 00292 * @param[in] message the message to be logged 00293 */ 00294 PN_EXTERN void pn_transport_log(pn_transport_t *transport, const char *message); 00295 00296 /** 00297 * Log a printf formatted message using a transport's logging 00298 * mechanism. 00299 * 00300 * This can be useful in a debugging context as the log message will 00301 * be prefixed with the transport's identifier. 00302 * 00303 * @param[in] transport a transport object 00304 * @param[in] fmt the printf formatted message to be logged 00305 * @param[in] ap a vector containing the format arguments 00306 */ 00307 PN_EXTERN void pn_transport_vlogf(pn_transport_t *transport, const char *fmt, va_list ap); 00308 00309 /** 00310 * Log a printf formatted message using a transport's logging 00311 * mechanism. 00312 * 00313 * This can be useful in a debugging context as the log message will 00314 * be prefixed with the transport's identifier. 00315 * 00316 * @param[in] transport a transport object 00317 * @param[in] fmt the printf formatted message to be logged 00318 */ 00319 PN_EXTERN void pn_transport_logf(pn_transport_t *transport, const char *fmt, ...); 00320 00321 /** 00322 * Get the maximum allowed channel for a transport. 00323 * This will be the minimum of 00324 * 1. limit imposed by this proton implementation 00325 * 2. limit imposed by remote peer 00326 * 3. limit imposed by this application, using pn_transport_set_channel_max() 00327 * 00328 * @param[in] transport a transport object 00329 * @return the maximum allowed channel 00330 */ 00331 PN_EXTERN uint16_t pn_transport_get_channel_max(pn_transport_t *transport); 00332 00333 /** 00334 * Set the maximum allowed channel number for a transport. 00335 * Note that this is the maximum channel number allowed, giving a 00336 * valid channel number range of [0..channel_max]. Therefore the 00337 * maximum number of simultaineously active channels will be 00338 * channel_max plus 1. 00339 * You can call this function more than once to raise and lower 00340 * the limit your application imposes on max channels for this 00341 * transport. However, smaller limits may be imposed by this 00342 * library, or by the remote peer. 00343 * After the OPEN frame has been sent to the remote peer, 00344 * further calls to this function will have no effect. 00345 * 00346 * @param[in] transport a transport object 00347 * @param[in] channel_max the maximum allowed channel 00348 * @return PN_OK, or PN_STATE_ERR if it is too late to change channel_max 00349 */ 00350 PN_EXTERN int pn_transport_set_channel_max(pn_transport_t *transport, uint16_t channel_max); 00351 00352 /** 00353 * Get the maximum allowed channel of a transport's remote peer. 00354 * 00355 * @param[in] transport a transport object 00356 * @return the maximum allowed channel of the transport's remote peer 00357 */ 00358 PN_EXTERN uint16_t pn_transport_remote_channel_max(pn_transport_t *transport); 00359 00360 /** 00361 * Get the maximum frame size of a transport. 00362 * 00363 * @param[in] transport a transport object 00364 * @return the maximum frame size of the transport object 00365 */ 00366 PN_EXTERN uint32_t pn_transport_get_max_frame(pn_transport_t *transport); 00367 00368 /** 00369 * Set the maximum frame size of a transport. 00370 * 00371 * @param[in] transport a transport object 00372 * @param[in] size the maximum frame size for the transport object 00373 */ 00374 PN_EXTERN void pn_transport_set_max_frame(pn_transport_t *transport, uint32_t size); 00375 00376 /** 00377 * Get the maximum frame size of a transport's remote peer. 00378 * 00379 * @param[in] transport a transport object 00380 * @return the maximum frame size of the transport's remote peer 00381 */ 00382 PN_EXTERN uint32_t pn_transport_get_remote_max_frame(pn_transport_t *transport); 00383 00384 /** 00385 * Get the idle timeout for a transport. 00386 * 00387 * A zero idle timeout means heartbeats are disabled. 00388 * 00389 * @param[in] transport a transport object 00390 * @return the transport's idle timeout 00391 */ 00392 PN_EXTERN pn_millis_t pn_transport_get_idle_timeout(pn_transport_t *transport); 00393 00394 /** 00395 * Set the idle timeout for a transport. 00396 * 00397 * A zero idle timeout means heartbeats are disabled. 00398 * 00399 * @param[in] transport a transport object 00400 * @param[in] timeout the idle timeout for the transport object 00401 */ 00402 PN_EXTERN void pn_transport_set_idle_timeout(pn_transport_t *transport, pn_millis_t timeout); 00403 00404 /** 00405 * Get the idle timeout for a transport's remote peer. 00406 * 00407 * A zero idle timeout means heartbeats are disabled. 00408 * 00409 * @param[in] transport a transport object 00410 * @return the idle timeout for the transport's remote peer 00411 */ 00412 PN_EXTERN pn_millis_t pn_transport_get_remote_idle_timeout(pn_transport_t *transport); 00413 00414 /** 00415 * @deprecated 00416 */ 00417 PN_EXTERN ssize_t pn_transport_input(pn_transport_t *transport, const char *bytes, size_t available); 00418 /** 00419 * @deprecated 00420 */ 00421 PN_EXTERN ssize_t pn_transport_output(pn_transport_t *transport, char *bytes, size_t size); 00422 00423 /** 00424 * Get the amount of free space for input following the transport's 00425 * tail pointer. 00426 * 00427 * If the engine is in an exceptional state such as encountering an 00428 * error condition or reaching the end of stream state, a negative 00429 * value will be returned indicating the condition. If an error is 00430 * indicated, futher details can be obtained from 00431 * ::pn_transport_error. Calls to ::pn_transport_process may alter the 00432 * value of this pointer. See ::pn_transport_process for details. 00433 * 00434 * @param[in] transport the transport 00435 * @return the free space in the transport, PN_EOS or error code if < 0 00436 */ 00437 PN_EXTERN ssize_t pn_transport_capacity(pn_transport_t *transport); 00438 00439 /** 00440 * Get the transport's tail pointer. 00441 * 00442 * The amount of free space following this pointer is reported by 00443 * ::pn_transport_capacity. Calls to ::pn_transport_process may alther 00444 * the value of this pointer. See ::pn_transport_process for details. 00445 * 00446 * @param[in] transport the transport 00447 * @return a pointer to the transport's input buffer, NULL if no capacity available. 00448 */ 00449 PN_EXTERN char *pn_transport_tail(pn_transport_t *transport); 00450 00451 /** 00452 * Pushes the supplied bytes into the tail of the transport. 00453 * 00454 * This is equivalent to copying @c size bytes afther the tail pointer 00455 * and then calling ::pn_transport_process with an argument of @c 00456 * size. Only some of the bytes will be copied if there is 00457 * insufficienty capacity available. Use ::pn_transport_capacity to 00458 * determine how much capacity the transport has. 00459 * 00460 * @param[in] transport the transport 00461 * @param[in] src the start of the data to push into the transport 00462 * @param[in] size the amount of data to push into the transport 00463 * 00464 * @return the number of bytes pushed on success, or error code if < 0 00465 */ 00466 PN_EXTERN ssize_t pn_transport_push(pn_transport_t *transport, const char *src, size_t size); 00467 00468 /** 00469 * Process input data following the tail pointer. 00470 * 00471 * Calling this function will cause the transport to consume @c size 00472 * bytes of input occupying the free space following the tail pointer. 00473 * Calls to this function may change the value of ::pn_transport_tail, 00474 * as well as the amount of free space reported by 00475 * ::pn_transport_capacity. 00476 * 00477 * @param[in] transport the transport 00478 * @param[in] size the amount of data written to the transport's input buffer 00479 * @return 0 on success, or error code if < 0 00480 */ 00481 PN_EXTERN int pn_transport_process(pn_transport_t *transport, size_t size); 00482 00483 /** 00484 * Indicate that the input has reached End Of Stream (EOS). 00485 * 00486 * This tells the transport that no more input will be forthcoming. 00487 * 00488 * @param[in] transport the transport 00489 * @return 0 on success, or error code if < 0 00490 */ 00491 PN_EXTERN int pn_transport_close_tail(pn_transport_t *transport); 00492 00493 /** 00494 * Get the number of pending output bytes following the transport's 00495 * head pointer. 00496 * 00497 * If the engine is in an exceptional state such as encountering an 00498 * error condition or reaching the end of stream state, a negative 00499 * value will be returned indicating the condition. If an error is 00500 * indicated, further details can be obtained from 00501 * ::pn_transport_error. Calls to ::pn_transport_pop may alter the 00502 * value of this pointer. See ::pn_transport_pop for details. 00503 * 00504 * @param[in] transport the transport 00505 * @return the number of pending output bytes, or an error code 00506 */ 00507 PN_EXTERN ssize_t pn_transport_pending(pn_transport_t *transport); 00508 00509 /** 00510 * Get the transport's head pointer. 00511 * 00512 * This pointer references queued output data. The 00513 * ::pn_transport_pending function reports how many bytes of output 00514 * data follow this pointer. Calls to ::pn_transport_pop may alter 00515 * this pointer and any data it references. See ::pn_transport_pop for 00516 * details. 00517 * 00518 * @param[in] transport the transport 00519 * @return a pointer to the transport's output buffer, or NULL if no pending output. 00520 */ 00521 PN_EXTERN const char *pn_transport_head(pn_transport_t *transport); 00522 00523 /** 00524 * Copies @c size bytes from the head of the transport to the @c dst 00525 * pointer. 00526 * 00527 * It is an error to call this with a value of @c size that is greater 00528 * than the value reported by ::pn_transport_pending. 00529 * 00530 * @param[in] transport the transport 00531 * @param[out] dst the destination buffer 00532 * @param[in] size the capacity of the destination buffer 00533 * @return number of bytes copied on success, or error code if < 0 00534 */ 00535 PN_EXTERN ssize_t pn_transport_peek(pn_transport_t *transport, char *dst, size_t size); 00536 00537 /** 00538 * Removes @c size bytes of output from the pending output queue 00539 * following the transport's head pointer. 00540 * 00541 * Calls to this function may alter the transport's head pointer as 00542 * well as the number of pending bytes reported by 00543 * ::pn_transport_pending. 00544 * 00545 * @param[in] transport the transport 00546 * @param[in] size the number of bytes to remove 00547 */ 00548 PN_EXTERN void pn_transport_pop(pn_transport_t *transport, size_t size); 00549 00550 /** 00551 * Indicate that the output has closed. 00552 * 00553 * This tells the transport that no more output will be popped. 00554 * 00555 * @param[in] transport the transport 00556 * @return 0 on success, or error code if < 0 00557 */ 00558 PN_EXTERN int pn_transport_close_head(pn_transport_t *transport); 00559 00560 /** 00561 * Check if a transport has buffered data. 00562 * 00563 * @param[in] transport a transport object 00564 * @return true if the transport has buffered data, false otherwise 00565 */ 00566 PN_EXTERN bool pn_transport_quiesced(pn_transport_t *transport); 00567 00568 /** 00569 * Check if a transport is closed. 00570 * 00571 * A transport is defined to be closed when both the tail and the head 00572 * are closed. In other words, when both ::pn_transport_capacity() < 0 00573 * and ::pn_transport_pending() < 0. 00574 * 00575 * @param[in] transport a transport object 00576 * @return true if the transport is closed, false otherwise 00577 */ 00578 PN_EXTERN bool pn_transport_closed(pn_transport_t *transport); 00579 00580 /** 00581 * Process any pending transport timer events. 00582 * 00583 * This method should be called after all pending input has been 00584 * processed by the transport (see ::pn_transport_input), and before 00585 * generating output (see ::pn_transport_output). It returns the 00586 * deadline for the next pending timer event, if any are present. 00587 * 00588 * @param[in] transport the transport to process. 00589 * @param[in] now the current time 00590 * 00591 * @return if non-zero, then the expiration time of the next pending timer event for the 00592 * transport. The caller must invoke pn_transport_tick again at least once at or before 00593 * this deadline occurs. 00594 */ 00595 PN_EXTERN pn_timestamp_t pn_transport_tick(pn_transport_t *transport, pn_timestamp_t now); 00596 00597 /** 00598 * Get the number of frames output by a transport. 00599 * 00600 * @param[in] transport a transport object 00601 * @return the number of frames output by the transport 00602 */ 00603 PN_EXTERN uint64_t pn_transport_get_frames_output(const pn_transport_t *transport); 00604 00605 /** 00606 * Get the number of frames input by a transport. 00607 * 00608 * @param[in] transport a transport object 00609 * @return the number of frames input by the transport 00610 */ 00611 PN_EXTERN uint64_t pn_transport_get_frames_input(const pn_transport_t *transport); 00612 00613 /** Access the AMQP Connection associated with the transport. 00614 * 00615 * @param[in] transport a transport object 00616 * @return the connection context for the transport, or NULL if 00617 * none 00618 */ 00619 PN_EXTERN pn_connection_t *pn_transport_connection(pn_transport_t *transport); 00620 00621 #ifdef __cplusplus 00622 } 00623 #endif 00624 00625 /** @} 00626 */ 00627 00628 #endif /* transport.h */