proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
proton
session.h
Go to the documentation of this file.
1
#ifndef PROTON_SESSION_H
2
#define PROTON_SESSION_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/type_compat.h
>
27
#include <stddef.h>
28
#include <sys/types.h>
29
30
#ifdef __cplusplus
31
extern
"C"
{
32
#endif
33
34
/** @file
35
* Session API for the proton Engine.
36
*
37
* @defgroup session Session
38
* @ingroup engine
39
* @{
40
*/
41
42
/**
43
* Factory for creating a new session on a given connection object.
44
*
45
* Creates a new session object and adds it to the set of sessions
46
* maintained by the connection object.
47
*
48
* @param[in] connection the connection object
49
* @return a pointer to the new session
50
*/
51
PN_EXTERN
pn_session_t
*
pn_session
(
pn_connection_t
*connection);
52
53
/**
54
* Free a session object.
55
*
56
* When a session object is freed, all ::pn_link_t, and
57
* ::pn_delivery_t objects associated with the session are also
58
* freed.
59
*
60
* @param[in] session a session object to free (or NULL)
61
*/
62
PN_EXTERN
void
pn_session_free
(
pn_session_t
*session);
63
64
/**
65
* Get the application context that is associated with a session
66
* object.
67
*
68
* The application context for a session may be set using
69
* ::pn_session_set_context.
70
*
71
* @param[in] session the session whose context is to be returned.
72
* @return the application context for the session object
73
*/
74
PN_EXTERN
void
*
pn_session_get_context
(
pn_session_t
*session);
75
76
/**
77
* Set a new application context for a session object.
78
*
79
* The application context for a session object may be retrieved
80
* using ::pn_session_get_context.
81
*
82
* @param[in] session the session object
83
* @param[in] context the application context
84
*/
85
PN_EXTERN
void
pn_session_set_context
(
pn_session_t
*session,
void
*context);
86
87
/**
88
* Get the endpoint state flags for a session.
89
*
90
* @param[in] session the session
91
* @return the session's state flags
92
*/
93
PN_EXTERN
pn_state_t
pn_session_state
(
pn_session_t
*session);
94
95
/**
96
* Get additional error information associated with the session.
97
*
98
* Whenever a session operation fails (i.e. returns an error code),
99
* additional error details can be obtained using this function. The
100
* error object that is returned may also be used to clear the error
101
* condition.
102
*
103
* The pointer returned by this operation is valid until the
104
* session object is freed.
105
*
106
* @param[in] session the sesion object
107
* @return the session's error object
108
*/
109
PN_EXTERN
pn_error_t
*
pn_session_error
(
pn_session_t
*session);
110
111
/**
112
* Get the local condition associated with the session endpoint.
113
*
114
* The ::pn_condition_t object retrieved may be modified prior to
115
* closing the session in order to indicate a particular condition
116
* exists when the session closes. This is normally used to
117
* communicate error conditions to the remote peer, however it may
118
* also be used in non error cases. See ::pn_condition_t for more
119
* details.
120
*
121
* The pointer returned by this operation is valid until the session
122
* object is freed.
123
*
124
* @param[in] session the session object
125
* @return the session's local condition object
126
*/
127
PN_EXTERN
pn_condition_t
*
pn_session_condition
(
pn_session_t
*session);
128
129
/**
130
* Get the remote condition associated with the session endpoint.
131
*
132
* The ::pn_condition_t object retrieved may be examined in order to
133
* determine whether the remote peer was indicating some sort of
134
* exceptional condition when the remote session endpoint was
135
* closed. The ::pn_condition_t object returned may not be modified.
136
*
137
* The pointer returned by this operation is valid until the
138
* session object is freed.
139
*
140
* @param[in] session the session object
141
* @return the session's remote condition object
142
*/
143
PN_EXTERN
pn_condition_t
*
pn_session_remote_condition
(
pn_session_t
*session);
144
145
/**
146
* Get the parent connection for a session object.
147
*
148
* This operation retrieves the parent pn_connection_t object that
149
* contains the given pn_session_t object.
150
*
151
* @param[in] session the session object
152
* @return the parent connection object
153
*/
154
PN_EXTERN
pn_connection_t
*
pn_session_connection
(
pn_session_t
*session);
155
156
/**
157
* Open a session.
158
*
159
* Once this operation has completed, the PN_LOCAL_ACTIVE state flag
160
* will be set.
161
*
162
* @param[in] session a session object
163
*/
164
PN_EXTERN
void
pn_session_open
(
pn_session_t
*session);
165
166
/**
167
* Close a session.
168
*
169
* Once this operation has completed, the PN_LOCAL_CLOSED state flag
170
* will be set. This may be called without calling
171
* ::pn_session_open, in this case it is equivalent to calling
172
* ::pn_session_open followed by ::pn_session_close.
173
*
174
* @param[in] session a session object
175
*/
176
PN_EXTERN
void
pn_session_close
(
pn_session_t
*session);
177
178
/**
179
* Get the incoming capacity of the session measured in bytes.
180
*
181
* The incoming capacity of a session determines how much incoming
182
* message data the session will buffer. Note that if this value is
183
* less than the negotiated frame size of the transport, it will be
184
* rounded up to one full frame.
185
*
186
* @param[in] session the session object
187
* @return the incoming capacity of the session in bytes
188
*/
189
PN_EXTERN
size_t
pn_session_get_incoming_capacity
(
pn_session_t
*session);
190
191
/**
192
* Set the incoming capacity for a session object.
193
*
194
* The incoming capacity of a session determines how much incoming
195
* message data the session will buffer. Note that if this value is
196
* less than the negotiated frame size of the transport, it will be
197
* rounded up to one full frame.
198
*
199
* @param[in] session the session object
200
* @param[in] capacity the incoming capacity for the session
201
*/
202
PN_EXTERN
void
pn_session_set_incoming_capacity
(
pn_session_t
*session,
size_t
capacity);
203
204
/**
205
* Get the number of outgoing bytes currently buffered by a session.
206
*
207
* @param[in] session a session object
208
* @return the number of outgoing bytes currently buffered
209
*/
210
PN_EXTERN
size_t
pn_session_outgoing_bytes
(
pn_session_t
*session);
211
212
/**
213
* Get the number of incoming bytes currently buffered by a session.
214
*
215
* @param[in] session a session object
216
* @return the number of incoming bytes currently buffered
217
*/
218
PN_EXTERN
size_t
pn_session_incoming_bytes
(
pn_session_t
*session);
219
220
/**
221
* Retrieve the first session from a given connection that matches the
222
* specified state mask.
223
*
224
* Examines the state of each session owned by the connection, and
225
* returns the first session that matches the given state mask. If
226
* state contains both local and remote flags, then an exact match
227
* against those flags is performed. If state contains only local or
228
* only remote flags, then a match occurs if any of the local or
229
* remote flags are set respectively.
230
*
231
* @param[in] connection to be searched for matching sessions
232
* @param[in] state mask to match
233
* @return the first session owned by the connection that matches the
234
* mask, else NULL if no sessions match
235
*/
236
PN_EXTERN
pn_session_t
*
pn_session_head
(
pn_connection_t
*connection,
pn_state_t
state);
237
238
/**
239
* Retrieve the next session from a given connection that matches the
240
* specified state mask.
241
*
242
* When used with ::pn_session_head, application can access all
243
* sessions on the connection that match the given state. See
244
* ::pn_session_head for description of match behavior.
245
*
246
* @param[in] session the previous session obtained from
247
* ::pn_session_head or ::pn_session_next
248
* @param[in] state mask to match.
249
* @return the next session owned by the connection that matches the
250
* mask, else NULL if no sessions match
251
*/
252
PN_EXTERN
pn_session_t
*
pn_session_next
(
pn_session_t
*session,
pn_state_t
state);
253
254
/** @}
255
*/
256
257
#ifdef __cplusplus
258
}
259
#endif
260
261
#endif
/* session.h */
Generated on Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1