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