00001 #ifndef PROTON_DRIVER_H 00002 #define PROTON_DRIVER_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/error.h> 00027 #include <proton/engine.h> 00028 #include <proton/sasl.h> 00029 #include <proton/selectable.h> 00030 #include <proton/ssl.h> 00031 00032 #ifdef __cplusplus 00033 extern "C" { 00034 #endif 00035 00036 /** @file 00037 * API for the Driver Layer. 00038 * 00039 * The driver library provides a simple implementation of a driver for 00040 * the proton engine. A driver is responsible for providing input, 00041 * output, and tick events to the bottom half of the engine API. See 00042 * ::pn_transport_input, ::pn_transport_output, and 00043 * ::pn_transport_tick. The driver also provides an interface for the 00044 * application to access the top half of the API when the state of the 00045 * engine may have changed due to I/O or timing events. Additionally 00046 * the driver incorporates the SASL engine as well in order to provide 00047 * a complete network stack: AMQP over SASL over TCP. 00048 * 00049 */ 00050 00051 typedef struct pn_driver_t pn_driver_t; 00052 typedef struct pn_listener_t pn_listener_t; 00053 typedef struct pn_connector_t pn_connector_t; 00054 00055 typedef enum { 00056 PN_CONNECTOR_WRITABLE, 00057 PN_CONNECTOR_READABLE 00058 } pn_activate_criteria_t; 00059 00060 /** Construct a driver 00061 * 00062 * Call pn_driver_free() to release the driver object. 00063 * @return new driver object, NULL if error 00064 */ 00065 PN_EXTERN pn_driver_t *pn_driver(void); 00066 00067 /** Return the most recent error code. 00068 * 00069 * @param[in] d the driver 00070 * 00071 * @return the most recent error text for d 00072 */ 00073 PN_EXTERN int pn_driver_errno(pn_driver_t *d); 00074 00075 /** Return the most recent error text for d. 00076 * 00077 * @param[in] d the driver 00078 * 00079 * @return the most recent error text for d 00080 */ 00081 PN_EXTERN const char *pn_driver_error(pn_driver_t *d); 00082 00083 /** Set the tracing level for the given driver. 00084 * 00085 * @param[in] driver the driver to trace 00086 * @param[in] trace the trace level to use. 00087 * @todo pn_trace_t needs documentation 00088 */ 00089 PN_EXTERN void pn_driver_trace(pn_driver_t *driver, pn_trace_t trace); 00090 00091 /** Force pn_driver_wait() to return 00092 * 00093 * @param[in] driver the driver to wake up 00094 * 00095 * @return zero on success, an error code on failure 00096 */ 00097 PN_EXTERN int pn_driver_wakeup(pn_driver_t *driver); 00098 00099 /** Wait for an active connector or listener 00100 * 00101 * @param[in] driver the driver to wait on 00102 * @param[in] timeout maximum time in milliseconds to wait, -1 means 00103 * infinite wait 00104 * 00105 * @return zero on success, an error code on failure 00106 */ 00107 PN_EXTERN int pn_driver_wait(pn_driver_t *driver, int timeout); 00108 00109 /** Get the next listener with pending data in the driver. 00110 * 00111 * @param[in] driver the driver 00112 * @return NULL if no active listener available 00113 */ 00114 PN_EXTERN pn_listener_t *pn_driver_listener(pn_driver_t *driver); 00115 00116 /** Get the next active connector in the driver. 00117 * 00118 * Returns the next connector with pending inbound data, available 00119 * capacity for outbound data, or pending tick. 00120 * 00121 * @param[in] driver the driver 00122 * @return NULL if no active connector available 00123 */ 00124 PN_EXTERN pn_connector_t *pn_driver_connector(pn_driver_t *driver); 00125 00126 /** Free the driver allocated via pn_driver, and all associated 00127 * listeners and connectors. 00128 * 00129 * @param[in] driver the driver to free, no longer valid on 00130 * return 00131 */ 00132 PN_EXTERN void pn_driver_free(pn_driver_t *driver); 00133 00134 00135 /** pn_listener - the server API **/ 00136 00137 /** Construct a listener for the given address. 00138 * 00139 * @param[in] driver driver that will 'own' this listener 00140 * @param[in] host local host address to listen on 00141 * @param[in] port local port to listen on 00142 * @param[in] context application-supplied, can be accessed via 00143 * pn_listener_context() 00144 * @return a new listener on the given host:port, NULL if error 00145 */ 00146 PN_EXTERN pn_listener_t *pn_listener(pn_driver_t *driver, const char *host, 00147 const char *port, void* context); 00148 00149 /** Access the head listener for a driver. 00150 * 00151 * @param[in] driver the driver whose head listener will be returned 00152 * 00153 * @return the head listener for driver or NULL if there is none 00154 */ 00155 PN_EXTERN pn_listener_t *pn_listener_head(pn_driver_t *driver); 00156 00157 /** Access the next listener. 00158 * 00159 * @param[in] listener the listener whose next listener will be 00160 * returned 00161 * 00162 * @return the next listener 00163 */ 00164 PN_EXTERN pn_listener_t *pn_listener_next(pn_listener_t *listener); 00165 00166 /** 00167 * @todo pn_listener_trace needs documentation 00168 */ 00169 PN_EXTERN void pn_listener_trace(pn_listener_t *listener, pn_trace_t trace); 00170 00171 /** Accept a connection that is pending on the listener. 00172 * 00173 * @param[in] listener the listener to accept the connection on 00174 * @return a new connector for the remote, or NULL on error 00175 */ 00176 PN_EXTERN pn_connector_t *pn_listener_accept(pn_listener_t *listener); 00177 00178 /** Access the application context that is associated with the listener. 00179 * 00180 * @param[in] listener the listener whose context is to be returned 00181 * @return the application context that was passed to pn_listener() or 00182 * pn_listener_fd() 00183 */ 00184 PN_EXTERN void *pn_listener_context(pn_listener_t *listener); 00185 00186 PN_EXTERN void pn_listener_set_context(pn_listener_t *listener, void *context); 00187 00188 /** Close the socket used by the listener. 00189 * 00190 * @param[in] listener the listener whose socket will be closed. 00191 */ 00192 PN_EXTERN void pn_listener_close(pn_listener_t *listener); 00193 00194 /** Frees the given listener. 00195 * 00196 * Assumes the listener's socket has been closed prior to call. 00197 * 00198 * @param[in] listener the listener object to free, no longer valid 00199 * on return 00200 */ 00201 PN_EXTERN void pn_listener_free(pn_listener_t *listener); 00202 00203 00204 00205 00206 /** pn_connector - the client API **/ 00207 00208 /** Construct a connector to the given remote address. 00209 * 00210 * @param[in] driver owner of this connection. 00211 * @param[in] host remote host to connect to. 00212 * @param[in] port remote port to connect to. 00213 * @param[in] context application supplied, can be accessed via 00214 * pn_connector_context() @return a new connector 00215 * to the given remote, or NULL on error. 00216 */ 00217 PN_EXTERN pn_connector_t *pn_connector(pn_driver_t *driver, const char *host, 00218 const char *port, void* context); 00219 00220 /** Access the head connector for a driver. 00221 * 00222 * @param[in] driver the driver whose head connector will be returned 00223 * 00224 * @return the head connector for driver or NULL if there is none 00225 */ 00226 PN_EXTERN pn_connector_t *pn_connector_head(pn_driver_t *driver); 00227 00228 /** Access the next connector. 00229 * 00230 * @param[in] connector the connector whose next connector will be 00231 * returned 00232 * 00233 * @return the next connector 00234 */ 00235 PN_EXTERN pn_connector_t *pn_connector_next(pn_connector_t *connector); 00236 00237 /** Set the tracing level for the given connector. 00238 * 00239 * @param[in] connector the connector to trace 00240 * @param[in] trace the trace level to use. 00241 */ 00242 PN_EXTERN void pn_connector_trace(pn_connector_t *connector, pn_trace_t trace); 00243 00244 /** Service the given connector. 00245 * 00246 * Handle any inbound data, outbound data, or timing events pending on 00247 * the connector. 00248 * 00249 * @param[in] connector the connector to process. 00250 */ 00251 PN_EXTERN void pn_connector_process(pn_connector_t *connector); 00252 00253 /** Access the listener which opened this connector. 00254 * 00255 * @param[in] connector connector whose listener will be returned. 00256 * @return the listener which created this connector, or NULL if the 00257 * connector has no listener (e.g. an outbound client 00258 * connection) 00259 */ 00260 PN_EXTERN pn_listener_t *pn_connector_listener(pn_connector_t *connector); 00261 00262 /** Access the Authentication and Security context of the connector. 00263 * 00264 * @param[in] connector connector whose security context will be 00265 * returned 00266 * @return the Authentication and Security context for the connector, 00267 * or NULL if none 00268 */ 00269 PN_EXTERN pn_sasl_t *pn_connector_sasl(pn_connector_t *connector); 00270 00271 /** Access the AMQP Connection associated with the connector. 00272 * 00273 * @param[in] connector the connector whose connection will be 00274 * returned 00275 * @return the connection context for the connector, or NULL if none 00276 */ 00277 PN_EXTERN pn_connection_t *pn_connector_connection(pn_connector_t *connector); 00278 00279 /** Assign the AMQP Connection associated with the connector. 00280 * 00281 * @param[in] connector the connector whose connection will be set. 00282 * @param[in] connection the connection to associate with the 00283 * connector 00284 */ 00285 PN_EXTERN void pn_connector_set_connection(pn_connector_t *connector, pn_connection_t *connection); 00286 00287 /** Access the application context that is associated with the 00288 * connector. 00289 * 00290 * @param[in] connector the connector whose context is to be returned. 00291 * @return the application context that was passed to pn_connector() 00292 * or pn_connector_fd() 00293 */ 00294 PN_EXTERN void *pn_connector_context(pn_connector_t *connector); 00295 00296 /** Assign a new application context to the connector. 00297 * 00298 * @param[in] connector the connector which will hold the context. 00299 * @param[in] context new application context to associate with the 00300 * connector 00301 */ 00302 PN_EXTERN void pn_connector_set_context(pn_connector_t *connector, void *context); 00303 00304 /** Access the name of the connector 00305 * 00306 * @param[in] connector the connector which will hole the name 00307 * @return the name of the connector in the form of a null-terminated character string. 00308 */ 00309 PN_EXTERN const char *pn_connector_name(const pn_connector_t *connector); 00310 00311 /** Access the transport used by this connector. 00312 * 00313 * @param[in] connector connector whose transport will be returned 00314 * @return the transport, or NULL if none 00315 */ 00316 PN_EXTERN pn_transport_t *pn_connector_transport(pn_connector_t *connector); 00317 00318 /** Close the socket used by the connector. 00319 * 00320 * @param[in] connector the connector whose socket will be closed 00321 */ 00322 PN_EXTERN void pn_connector_close(pn_connector_t *connector); 00323 00324 /** Determine if the connector is closed. 00325 * 00326 * @return True if closed, otherwise false 00327 */ 00328 PN_EXTERN bool pn_connector_closed(pn_connector_t *connector); 00329 00330 /** Destructor for the given connector. 00331 * 00332 * Assumes the connector's socket has been closed prior to call. 00333 * 00334 * @param[in] connector the connector object to free. No longer 00335 * valid on return 00336 */ 00337 PN_EXTERN void pn_connector_free(pn_connector_t *connector); 00338 00339 /** Activate a connector when a criteria is met 00340 * 00341 * Set a criteria for a connector (i.e. it's transport is writable) that, once met, 00342 * the connector shall be placed in the driver's work queue. 00343 * 00344 * @param[in] connector The connector object to activate 00345 * @param[in] criteria The criteria that must be met prior to activating the connector 00346 */ 00347 PN_EXTERN void pn_connector_activate(pn_connector_t *connector, pn_activate_criteria_t criteria); 00348 00349 /** Return the activation status of the connector for a criteria 00350 * 00351 * Return the activation status (i.e. readable, writable) for the connector. This function 00352 * has the side-effect of canceling the activation of the criteria. 00353 * 00354 * Please note that this function must not be used for normal AMQP connectors. It is only 00355 * used for connectors created so the driver can track non-AMQP file descriptors. Such 00356 * connectors are never passed into pn_connector_process. 00357 * 00358 * @param[in] connector The connector object to activate 00359 * @param[in] criteria The criteria to test. "Is this the reason the connector appeared 00360 * in the work list?" 00361 * @return true iff the criteria is activated on the connector. 00362 */ 00363 PN_EXTERN bool pn_connector_activated(pn_connector_t *connector, pn_activate_criteria_t criteria); 00364 00365 00366 #ifdef __cplusplus 00367 } 00368 #endif 00369 00370 #endif /* driver.h */