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