proton  0
connection.h
Go to the documentation of this file.
1 #ifndef PROTON_CONNECTION_H
2 #define PROTON_CONNECTION_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/codec.h>
27 #include <proton/condition.h>
28 #include <proton/error.h>
29 #include <proton/type_compat.h>
30 #include <proton/types.h>
31 
32 #include <stddef.h>
33 #include <sys/types.h>
34 
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38 
39 /**
40  * @file
41  *
42  * Connection API for the proton Engine.
43  *
44  * @defgroup connection Connection
45  * @ingroup engine
46  * @{
47  */
48 
49 /**
50  * The local @link pn_state_t endpoint state @endlink is uninitialized.
51  */
52 #define PN_LOCAL_UNINIT (1)
53 /**
54  * The local @link pn_state_t endpoint state @endlink is active.
55  */
56 #define PN_LOCAL_ACTIVE (2)
57 /**
58  * The local @link pn_state_t endpoint state @endlink is closed.
59  */
60 #define PN_LOCAL_CLOSED (4)
61 /**
62  * The remote @link pn_state_t endpoint state @endlink is uninitialized.
63  */
64 #define PN_REMOTE_UNINIT (8)
65 /**
66  * The remote @link pn_state_t endpoint state @endlink is active.
67  */
68 #define PN_REMOTE_ACTIVE (16)
69 /**
70  * The remote @link pn_state_t endpoint state @endlink is closed.
71  */
72 #define PN_REMOTE_CLOSED (32)
73 
74 /**
75  * A mask for values of ::pn_state_t that preserves only the local
76  * bits of an endpoint's state.
77  */
78 #define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED)
79 
80 /**
81  * A mask for values of ::pn_state_t that preserves only the remote
82  * bits of an endpoint's state.
83  */
84 #define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED)
85 
86 /**
87  * Factory to construct a new Connection.
88  *
89  * @return pointer to a new connection object.
90  */
92 
93 /**
94  * Free a connection object.
95  *
96  * When a connection object is freed, all ::pn_session_t, ::pn_link_t,
97  * and ::pn_delivery_t objects associated with the connection are also
98  * freed.
99  *
100  * @param[in] connection the connection object to free (or NULL)
101  */
103 
104 /**
105  * Release a connection object.
106  *
107  * When a connection object is released, all ::pn_session_t and
108  * ::pn_link_t, objects associated with the connection are also
109  * released and all ::pn_delivery_t objects are settled.
110  *
111  * @param[in] connection the connection object to be released
112  */
114 
115 /**
116  * Get additional error information associated with the connection.
117  *
118  * Whenever a connection operation fails (i.e. returns an error code),
119  * additional error details can be obtained using this function. The
120  * error object that is returned may also be used to clear the error
121  * condition.
122  *
123  * The pointer returned by this operation is valid until the
124  * connection object is freed.
125  *
126  * @param[in] connection the connection object
127  * @return the connection's error object
128  */
130 
131 /**
132  * Associate a connection object with an event collector.
133  *
134  * By associating a connection object with an event collector, key
135  * changes in endpoint state are reported to the collector via
136  * ::pn_event_t objects that can be inspected and processed. See
137  * ::pn_event_t for more details on the kinds of events.
138  *
139  * Note that by registering a collector, the user is requesting that
140  * an indefinite number of events be queued up on his behalf. This
141  * means that unless the application eventually processes these
142  * events, the storage requirements for keeping them will grow without
143  * bound. In other words, don't register a collector with a connection
144  * if you never intend to process any of the events.
145  *
146  * @param[in] connection the connection object
147  * @param[in] collector the event collector
148  */
149 PN_EXTERN void pn_connection_collect(pn_connection_t *connection, pn_collector_t *collector);
150 
151 /**
152  * @deprecated
153  * Get the application context that is associated with a connection
154  * object.
155  *
156  * The application context for a connection may be set using
157  * ::pn_connection_set_context.
158  *
159  * @param[in] connection the connection whose context is to be returned.
160  * @return the application context for the connection object
161  */
163 
164 /**
165  * @deprecated
166  * Set a new application context for a connection object.
167  *
168  * The application context for a connection object may be retrieved
169  * using ::pn_connection_get_context.
170  *
171  * @param[in] connection the connection object
172  * @param[in] context the application context
173  */
174 PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context);
175 
176 /**
177  * Get the attachments that are associated with a connection object.
178  *
179  * @param[in] connection the connection whose attachments are to be returned.
180  * @return the attachments for the connection object
181  */
183 
184 /**
185  * Get the endpoint state flags for a connection.
186  *
187  * @param[in] connection the connection
188  * @return the connection's state flags
189  */
191 
192 /**
193  * Open a connection.
194  *
195  * Once this operation has completed, the PN_LOCAL_ACTIVE state flag
196  * will be set.
197  *
198  * @param[in] connection a connection object
199  */
201 
202 /**
203  * Close a connection.
204  *
205  * Once this operation has completed, the PN_LOCAL_CLOSED state flag
206  * will be set. This may be called without calling
207  * ::pn_connection_open, in this case it is equivalent to calling
208  * ::pn_connection_open followed by ::pn_connection_close.
209  *
210  * @param[in] connection a connection object
211  */
213 
214 /**
215  * Reset a connection object back to the uninitialized state.
216  *
217  * Note that this does *not* remove any contained ::pn_session_t,
218  * ::pn_link_t, and ::pn_delivery_t objects.
219  *
220  * @param[in] connection a connection object
221  */
223 
224 /**
225  * Get the local condition associated with the connection endpoint.
226  *
227  * The ::pn_condition_t object retrieved may be modified prior to
228  * closing the connection in order to indicate a particular condition
229  * exists when the connection closes. This is normally used to
230  * communicate error conditions to the remote peer, however it may
231  * also be used in non error cases such as redirects. See
232  * ::pn_condition_t for more details.
233  *
234  * The pointer returned by this operation is valid until the
235  * connection object is freed.
236  *
237  * @param[in] connection the connection object
238  * @return the connection's local condition object
239  */
241 
242 /**
243  * Get the remote condition associated with the connection endpoint.
244  *
245  * The ::pn_condition_t object retrieved may be examined in order to
246  * determine whether the remote peer was indicating some sort of
247  * exceptional condition when the remote connection endpoint was
248  * closed. The ::pn_condition_t object returned may not be modified.
249  *
250  * The pointer returned by this operation is valid until the
251  * connection object is freed.
252  *
253  * @param[in] connection the connection object
254  * @return the connection's remote condition object
255  */
257 
258 /**
259  * Get the AMQP Container name advertised by a connection object.
260  *
261  * The pointer returned by this operation is valid until
262  * ::pn_connection_set_container is called, or until the connection
263  * object is freed, whichever happens sooner.
264  *
265  * @param[in] connection the connection object
266  * @return a pointer to the container name
267  */
268 PN_EXTERN const char *pn_connection_get_container(pn_connection_t *connection);
269 
270 /**
271  * Set the AMQP Container name advertised by a connection object.
272  *
273  * @param[in] connection the connection object
274  * @param[in] container the container name
275  */
276 PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container);
277 
278 /**
279  * Get the value of the AMQP Hostname used by a connection object.
280  *
281  * The pointer returned by this operation is valid until
282  * ::pn_connection_set_hostname is called, or until the connection
283  * object is freed, whichever happens sooner.
284  *
285  * @param[in] connection the connection object
286  * @return a pointer to the hostname
287  */
288 PN_EXTERN const char *pn_connection_get_hostname(pn_connection_t *connection);
289 
290 /**
291  * Set the value of the AMQP Hostname used by a connection object.
292  *
293  * @param[in] connection the connection object
294  * @param[in] hostname the hostname
295  */
296 PN_EXTERN void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname);
297 
298 /**
299  * Get the AMQP Container name advertised by the remote connection
300  * endpoint.
301  *
302  * This will return NULL until the ::PN_REMOTE_ACTIVE state is
303  * reached. See ::pn_state_t for more details on endpoint state.
304  *
305  * Any non null pointer returned by this operation will be valid until
306  * the connection object is unbound from a transport or freed,
307  * whichever happens sooner.
308  *
309  * @param[in] connection the connection object
310  * @return a pointer to the remote container name
311  */
313 
314 /**
315  * Get the AMQP Hostname set by the remote connection endpoint.
316  *
317  * This will return NULL until the ::PN_REMOTE_ACTIVE state is
318  * reached. See ::pn_state_t for more details on endpoint state.
319  *
320  * Any non null pointer returned by this operation will be valid until
321  * the connection object is unbound from a transport or freed,
322  * whichever happens sooner.
323  *
324  * @param[in] connection the connection object
325  * @return a pointer to the remote hostname
326  */
328 
329 /**
330  * Access/modify the AMQP offered capabilities data for a connection
331  * object.
332  *
333  * This operation will return a pointer to a ::pn_data_t object that
334  * is valid until the connection object is freed. Any data contained
335  * by the ::pn_data_t object will be sent as the offered capabilites
336  * for the parent connection object. Note that this MUST take the form
337  * of an array of symbols to be valid.
338  *
339  * The ::pn_data_t pointer returned is valid until the connection
340  * object is freed.
341  *
342  * @param[in] connection the connection object
343  * @return a pointer to a pn_data_t representing the offered capabilities
344  */
346 
347 /**
348  * Access/modify the AMQP desired capabilities data for a connection
349  * object.
350  *
351  * This operation will return a pointer to a ::pn_data_t object that
352  * is valid until the connection object is freed. Any data contained
353  * by the ::pn_data_t object will be sent as the desired capabilites
354  * for the parent connection object. Note that this MUST take the form
355  * of an array of symbols to be valid.
356  *
357  * The ::pn_data_t pointer returned is valid until the connection
358  * object is freed.
359  *
360  * @param[in] connection the connection object
361  * @return a pointer to a pn_data_t representing the desired capabilities
362  */
364 
365 /**
366  * Access/modify the AMQP properties data for a connection object.
367  *
368  * This operation will return a pointer to a ::pn_data_t object that
369  * is valid until the connection object is freed. Any data contained
370  * by the ::pn_data_t object will be sent as the AMQP properties for
371  * the parent connection object. Note that this MUST take the form of
372  * a symbol keyed map to be valid.
373  *
374  * The ::pn_data_t pointer returned is valid until the connection
375  * object is freed.
376  *
377  * @param[in] connection the connection object
378  * @return a pointer to a pn_data_t representing the connection properties
379  */
381 
382 /**
383  * Access the AMQP offered capabilites supplied by the remote
384  * connection endpoint.
385  *
386  * This operation will return a pointer to a ::pn_data_t object that
387  * is valid until the connection object is freed. This data object
388  * will be empty until the remote connection is opened as indicated by
389  * the ::PN_REMOTE_ACTIVE flag.
390  *
391  * @param[in] connection the connection object
392  * @return the remote offered capabilities
393  */
395 
396 /**
397  * Access the AMQP desired capabilites supplied by the remote
398  * connection endpoint.
399  *
400  * This operation will return a pointer to a ::pn_data_t object that
401  * is valid until the connection object is freed. This data object
402  * will be empty until the remote connection is opened as indicated by
403  * the ::PN_REMOTE_ACTIVE flag.
404  *
405  * @param[in] connection the connection object
406  * @return the remote desired capabilities
407  */
409 
410 /**
411  * Access the AMQP connection properties supplied by the remote
412  * connection endpoint.
413  *
414  * This operation will return a pointer to a ::pn_data_t object that
415  * is valid until the connection object is freed. This data object
416  * will be empty until the remote connection is opened as indicated by
417  * the ::PN_REMOTE_ACTIVE flag.
418  *
419  * @param[in] connection the connection object
420  * @return the remote connection properties
421  */
423 
424 /**
425  * Get the transport bound to a connection object.
426  *
427  * If the connection is unbound, then this operation will return NULL.
428  *
429  * @param[in] connection the connection object
430  * @return the transport bound to a connection, or NULL if the
431  * connection is unbound
432  */
434 
435 /** @}
436  */
437 
438 #ifdef __cplusplus
439 }
440 #endif
441 
442 #endif /* connection.h */
PN_EXTERN void * pn_connection_get_context(pn_connection_t *connection)
The Condition API for the proton Engine.
PN_EXTERN pn_condition_t * pn_connection_condition(pn_connection_t *connection)
Get the local condition associated with the connection endpoint.
PN_EXTERN const char * pn_connection_remote_container(pn_connection_t *connection)
Get the AMQP Container name advertised by the remote connection endpoint.
struct pn_error_t pn_error_t
Definition: error.h:32
PN_EXTERN pn_transport_t * pn_connection_transport(pn_connection_t *connection)
Get the transport bound to a connection object.
struct pn_record_t pn_record_t
Definition: object.h:46
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:112
PN_EXTERN void pn_connection_release(pn_connection_t *connection)
Release a connection object.
PN_EXTERN pn_data_t * pn_connection_properties(pn_connection_t *connection)
Access/modify the AMQP properties data for a connection object.
PN_EXTERN pn_record_t * pn_connection_attachments(pn_connection_t *connection)
Get the attachments that are associated with a connection object.
struct pn_data_t pn_data_t
An AMQP Data object.
Definition: codec.h:352
struct pn_collector_t pn_collector_t
An event collector.
Definition: types.h:244
PN_EXTERN pn_data_t * pn_connection_desired_capabilities(pn_connection_t *connection)
Access/modify the AMQP desired capabilities data for a connection object.
PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container)
Set the AMQP Container name advertised by a connection object.
Data API for proton.
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN pn_data_t * pn_connection_remote_desired_capabilities(pn_connection_t *connection)
Access the AMQP desired capabilites supplied by the remote connection endpoint.
PN_EXTERN void pn_connection_free(pn_connection_t *connection)
Free a connection object.
PN_EXTERN pn_connection_t * pn_connection(void)
Factory to construct a new Connection.
PN_EXTERN pn_data_t * pn_connection_remote_properties(pn_connection_t *connection)
Access the AMQP connection properties supplied by the remote connection endpoint. ...
PN_EXTERN pn_state_t pn_connection_state(pn_connection_t *connection)
Get the endpoint state flags for a connection.
PN_EXTERN const char * pn_connection_get_hostname(pn_connection_t *connection)
Get the value of the AMQP Hostname used by a connection object.
PN_EXTERN pn_condition_t * pn_connection_remote_condition(pn_connection_t *connection)
Get the remote condition associated with the connection endpoint.
PN_EXTERN const char * pn_connection_get_container(pn_connection_t *connection)
Get the AMQP Container name advertised by a connection object.
PN_EXTERN void pn_connection_collect(pn_connection_t *connection, pn_collector_t *collector)
Associate a connection object with an event collector.
PN_EXTERN void pn_connection_open(pn_connection_t *connection)
Open a connection.
PN_EXTERN void pn_connection_close(pn_connection_t *connection)
Close a connection.
PN_EXTERN pn_data_t * pn_connection_offered_capabilities(pn_connection_t *connection)
Access/modify the AMQP offered capabilities data for a connection object.
PN_EXTERN pn_error_t * pn_connection_error(pn_connection_t *connection)
Get additional error information associated with the connection.
PN_EXTERN pn_data_t * pn_connection_remote_offered_capabilities(pn_connection_t *connection)
Access the AMQP offered capabilites supplied by the remote connection endpoint.
PN_EXTERN const char * pn_connection_remote_hostname(pn_connection_t *connection)
Get the AMQP Hostname set by the remote connection endpoint.
PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context)
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:256
PN_EXTERN void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname)
Set the value of the AMQP Hostname used by a connection object.
struct pn_condition_t pn_condition_t
An AMQP Condition object.
Definition: condition.h:65
int pn_state_t
Holds the state flags for an AMQP endpoint.
Definition: types.h:97
PN_EXTERN void pn_connection_reset(pn_connection_t *connection)
Reset a connection object back to the uninitialized state.