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/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
;
50
typedef
struct
pn_listener_t
pn_listener_t
;
51
typedef
struct
pn_connector_t
pn_connector_t
;
52
53
typedef
enum
{
54
PN_CONNECTOR_WRITABLE
,
55
PN_CONNECTOR_READABLE
56
}
pn_activate_criteria_t
;
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
*/
71
int
pn_driver_errno
(
pn_driver_t
*d);
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
*/
112
pn_listener_t
*
pn_driver_listener
(
pn_driver_t
*driver);
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
*/
122
pn_connector_t
*
pn_driver_connector
(
pn_driver_t
*driver);
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
*/
163
pn_listener_t
*
pn_listener_head
(
pn_driver_t
*driver);
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
*/
172
pn_listener_t
*
pn_listener_next
(
pn_listener_t
*listener);
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
*/
184
pn_connector_t
*
pn_listener_accept
(
pn_listener_t
*listener);
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
*/
244
pn_connector_t
*
pn_connector_head
(
pn_driver_t
*driver);
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
*/
253
pn_connector_t
*
pn_connector_next
(
pn_connector_t
*connector);
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
*/
278
pn_listener_t
*
pn_connector_listener
(
pn_connector_t
*connector);
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
*/
287
pn_sasl_t
*
pn_connector_sasl
(
pn_connector_t
*connector);
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
*/
295
pn_connection_t
*
pn_connector_connection
(
pn_connector_t
*connector);
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
*/
328
pn_transport_t
*
pn_connector_transport
(
pn_connector_t
*connector);
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
*/
359
void
pn_connector_activate
(
pn_connector_t
*connector,
pn_activate_criteria_t
criteria);
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
*/
375
bool
pn_connector_activated
(
pn_connector_t
*connector,
pn_activate_criteria_t
criteria);
376
377
378
#ifdef __cplusplus
379
}
380
#endif
381
382
#endif
/* driver.h */
Generated on Mon Feb 11 2013 20:34:32 for proton by
1.8.1.1