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