proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
driver.h
Go to the documentation of this file.
1 #ifndef PROTON_DRIVER_H
2 #define PROTON_DRIVER_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/error.h>
26 #include <proton/engine.h>
27 #include <proton/sasl.h>
28 #include <proton/ssl.h>
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /** @file
35  * API for the Driver Layer.
36  *
37  * The driver library provides a simple implementation of a driver for
38  * the proton engine. A driver is responsible for providing input,
39  * output, and tick events to the bottom half of the engine API. See
40  * ::pn_transport_input, ::pn_transport_output, and
41  * ::pn_transport_tick. The driver also provides an interface for the
42  * application to access the top half of the API when the state of the
43  * engine may have changed due to I/O or timing events. Additionally
44  * the driver incorporates the SASL engine as well in order to provide
45  * a complete network stack: AMQP over SASL over TCP.
46  *
47  */
48 
49 typedef struct pn_driver_t pn_driver_t;
52 
53 typedef enum {
57 
58 /** Construct a driver
59  *
60  * Call pn_driver_free() to release the driver object.
61  * @return new driver object, NULL if error
62  */
63 pn_driver_t *pn_driver(void);
64 
65 /** Return the most recent error code.
66  *
67  * @param[in] d the driver
68  *
69  * @return the most recent error text for d
70  */
72 
73 /** Return the most recent error text for d.
74  *
75  * @param[in] d the driver
76  *
77  * @return the most recent error text for d
78  */
79 const char *pn_driver_error(pn_driver_t *d);
80 
81 /** Set the tracing level for the given driver.
82  *
83  * @param[in] driver the driver to trace
84  * @param[in] trace the trace level to use.
85  * @todo pn_trace_t needs documentation
86  */
87 void pn_driver_trace(pn_driver_t *driver, pn_trace_t trace);
88 
89 /** Force pn_driver_wait() to return
90  *
91  * @param[in] driver the driver to wake up
92  *
93  * @return zero on success, an error code on failure
94  */
95 int pn_driver_wakeup(pn_driver_t *driver);
96 
97 /** Wait for an active connector or listener
98  *
99  * @param[in] driver the driver to wait on
100  * @param[in] timeout maximum time in milliseconds to wait, -1 means
101  * infinite wait
102  *
103  * @return zero on success, an error code on failure
104  */
105 int pn_driver_wait(pn_driver_t *driver, int timeout);
106 
107 /** Get the next listener with pending data in the driver.
108  *
109  * @param[in] driver the driver
110  * @return NULL if no active listener available
111  */
113 
114 /** Get the next active connector in the driver.
115  *
116  * Returns the next connector with pending inbound data, available
117  * capacity for outbound data, or pending tick.
118  *
119  * @param[in] driver the driver
120  * @return NULL if no active connector available
121  */
123 
124 /** Free the driver allocated via pn_driver, and all associated
125  * listeners and connectors.
126  *
127  * @param[in] driver the driver to free, no longer valid on
128  * return
129  */
130 void pn_driver_free(pn_driver_t *driver);
131 
132 
133 /** pn_listener - the server API **/
134 
135 /** Construct a listener for the given address.
136  *
137  * @param[in] driver driver that will 'own' this listener
138  * @param[in] host local host address to listen on
139  * @param[in] port local port to listen on
140  * @param[in] context application-supplied, can be accessed via
141  * pn_listener_context()
142  * @return a new listener on the given host:port, NULL if error
143  */
144 pn_listener_t *pn_listener(pn_driver_t *driver, const char *host,
145  const char *port, void* context);
146 
147 /** Create a listener using the existing file descriptor.
148  *
149  * @param[in] driver driver that will 'own' this listener
150  * @param[in] fd existing file descriptor for listener to listen on
151  * @param[in] context application-supplied, can be accessed via
152  * pn_listener_context()
153  * @return a new listener on the given host:port, NULL if error
154  */
155 pn_listener_t *pn_listener_fd(pn_driver_t *driver, int fd, void *context);
156 
157 /** Access the head listener for a driver.
158  *
159  * @param[in] driver the driver whose head listener will be returned
160  *
161  * @return the head listener for driver or NULL if there is none
162  */
164 
165 /** Access the next listener.
166  *
167  * @param[in] listener the listener whose next listener will be
168  * returned
169  *
170  * @return the next listener
171  */
173 
174 /**
175  * @todo pn_listener_trace needs documentation
176  */
177 void pn_listener_trace(pn_listener_t *listener, pn_trace_t trace);
178 
179 /** Accept a connection that is pending on the listener.
180  *
181  * @param[in] listener the listener to accept the connection on
182  * @return a new connector for the remote, or NULL on error
183  */
185 
186 /** Access the application context that is associated with the listener.
187  *
188  * @param[in] listener the listener whose context is to be returned
189  * @return the application context that was passed to pn_listener() or
190  * pn_listener_fd()
191  */
192 void *pn_listener_context(pn_listener_t *listener);
193 
194 void pn_listener_set_context(pn_listener_t *listener, void *context);
195 
196 /** Close the socket used by the listener.
197  *
198  * @param[in] listener the listener whose socket will be closed.
199  */
200 void pn_listener_close(pn_listener_t *listener);
201 
202 /** Frees the given listener.
203  *
204  * Assumes the listener's socket has been closed prior to call.
205  *
206  * @param[in] listener the listener object to free, no longer valid
207  * on return
208  */
209 void pn_listener_free(pn_listener_t *listener);
210 
211 
212 
213 
214 /** pn_connector - the client API **/
215 
216 /** Construct a connector to the given remote address.
217  *
218  * @param[in] driver owner of this connection.
219  * @param[in] host remote host to connect to.
220  * @param[in] port remote port to connect to.
221  * @param[in] context application supplied, can be accessed via
222  * pn_connector_context() @return a new connector
223  * to the given remote, or NULL on error.
224  */
225 pn_connector_t *pn_connector(pn_driver_t *driver, const char *host,
226  const char *port, void* context);
227 
228 /** Create a connector using the existing file descriptor.
229  *
230  * @param[in] driver driver that will 'own' this connector.
231  * @param[in] fd existing file descriptor to use for this connector.
232  * @param[in] context application-supplied, can be accessed via
233  * pn_connector_context()
234  * @return a new connector to the given host:port, NULL if error.
235  */
236 pn_connector_t *pn_connector_fd(pn_driver_t *driver, int fd, void *context);
237 
238 /** Access the head connector for a driver.
239  *
240  * @param[in] driver the driver whose head connector will be returned
241  *
242  * @return the head connector for driver or NULL if there is none
243  */
245 
246 /** Access the next connector.
247  *
248  * @param[in] connector the connector whose next connector will be
249  * returned
250  *
251  * @return the next connector
252  */
254 
255 /** Set the tracing level for the given connector.
256  *
257  * @param[in] connector the connector to trace
258  * @param[in] trace the trace level to use.
259  */
260 void pn_connector_trace(pn_connector_t *connector, pn_trace_t trace);
261 
262 /** Service the given connector.
263  *
264  * Handle any inbound data, outbound data, or timing events pending on
265  * the connector.
266  *
267  * @param[in] connector the connector to process.
268  */
269 void pn_connector_process(pn_connector_t *connector);
270 
271 /** Access the listener which opened this connector.
272  *
273  * @param[in] connector connector whose listener will be returned.
274  * @return the listener which created this connector, or NULL if the
275  * connector has no listener (e.g. an outbound client
276  * connection)
277  */
279 
280 /** Access the Authentication and Security context of the connector.
281  *
282  * @param[in] connector connector whose security context will be
283  * returned
284  * @return the Authentication and Security context for the connector,
285  * or NULL if none
286  */
288 
289 /** Access the AMQP Connection associated with the connector.
290  *
291  * @param[in] connector the connector whose connection will be
292  * returned
293  * @return the connection context for the connector, or NULL if none
294  */
296 
297 /** Assign the AMQP Connection associated with the connector.
298  *
299  * @param[in] connector the connector whose connection will be set.
300  * @param[in] connection the connection to associate with the
301  * connector
302  */
303 void pn_connector_set_connection(pn_connector_t *connector, pn_connection_t *connection);
304 
305 /** Access the application context that is associated with the
306  * connector.
307  *
308  * @param[in] connector the connector whose context is to be returned.
309 
310  * @return the application context that was passed to pn_connector()
311  * or pn_connector_fd()
312  */
313 void *pn_connector_context(pn_connector_t *connector);
314 
315 /** Assign a new application context to the connector.
316  *
317  * @param[in] connector the connector which will hold the context.
318  * @param[in] context new application context to associate with the
319  * connector
320  */
321 void pn_connector_set_context(pn_connector_t *connector, void *context);
322 
323 /** Access the transport used by this connector.
324  *
325  * @param[in] connector connector whose transport will be returned
326  * @return the transport, or NULL if none
327  */
329 
330 /** Close the socket used by the connector.
331  *
332  * @param[in] connector the connector whose socket will be closed
333  */
334 void pn_connector_close(pn_connector_t *connector);
335 
336 /** Determine if the connector is closed.
337  *
338  * @return True if closed, otherwise false
339  */
340 bool pn_connector_closed(pn_connector_t *connector);
341 
342 /** Destructor for the given connector.
343  *
344  * Assumes the connector's socket has been closed prior to call.
345  *
346  * @param[in] connector the connector object to free. No longer
347  * valid on return
348  */
349 void pn_connector_free(pn_connector_t *connector);
350 
351 /** Activate a connector when a criteria is met
352  *
353  * Set a criteria for a connector (i.e. it's transport is writable) that, once met,
354  * the connector shall be placed in the driver's work queue.
355  *
356  * @param[in] connector The connector object to activate
357  * @param[in] criteria The criteria that must be met prior to activating the connector
358  */
360 
361 /** Return the activation status of the connector for a criteria
362  *
363  * Return the activation status (i.e. readable, writable) for the connector. This function
364  * has the side-effect of canceling the activation of the criteria.
365  *
366  * Please note that this function must not be used for normal AMQP connectors. It is only
367  * used for connectors created so the driver can track non-AMQP file descriptors. Such
368  * connectors are never passed into pn_connector_process.
369  *
370  * @param[in] connector The connector object to activate
371  * @param[in] criteria The criteria to test. "Is this the reason the connector appeared
372  * in the work list?"
373  * @return true iff the criteria is activated on the connector.
374  */
376 
377 
378 #ifdef __cplusplus
379 }
380 #endif
381 
382 #endif /* driver.h */