00001 #ifndef PROTON_SESSION_H 00002 #define PROTON_SESSION_H 1 00003 00004 /* 00005 * 00006 * Licensed to the Apache Software Foundation (ASF) under one 00007 * or more contributor license agreements. See the NOTICE file 00008 * distributed with this work for additional information 00009 * regarding copyright ownership. The ASF licenses this file 00010 * to you under the Apache License, Version 2.0 (the 00011 * "License"); you may not use this file except in compliance 00012 * with the License. You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, 00017 * software distributed under the License is distributed on an 00018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00019 * KIND, either express or implied. See the License for the 00020 * specific language governing permissions and limitations 00021 * under the License. 00022 * 00023 */ 00024 00025 #include <proton/import_export.h> 00026 #include <proton/type_compat.h> 00027 #include <stddef.h> 00028 #include <sys/types.h> 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif 00033 00034 /** @file 00035 * Session API for the proton Engine. 00036 * 00037 * @defgroup session Session 00038 * @ingroup engine 00039 * @{ 00040 */ 00041 00042 /** 00043 * Factory for creating a new session on a given connection object. 00044 * 00045 * Creates a new session object and adds it to the set of sessions 00046 * maintained by the connection object. 00047 * 00048 * @param[in] connection the connection object 00049 * @return a pointer to the new session 00050 */ 00051 PN_EXTERN pn_session_t *pn_session(pn_connection_t *connection); 00052 00053 /** 00054 * Free a session object. 00055 * 00056 * When a session object is freed, all ::pn_link_t, and 00057 * ::pn_delivery_t objects associated with the session are also 00058 * freed. 00059 * 00060 * @param[in] session a session object to free (or NULL) 00061 */ 00062 PN_EXTERN void pn_session_free(pn_session_t *session); 00063 00064 /** 00065 * Get the application context that is associated with a session 00066 * object. 00067 * 00068 * The application context for a session may be set using 00069 * ::pn_session_set_context. 00070 * 00071 * @param[in] session the session whose context is to be returned. 00072 * @return the application context for the session object 00073 */ 00074 PN_EXTERN void *pn_session_get_context(pn_session_t *session); 00075 00076 /** 00077 * Set a new application context for a session object. 00078 * 00079 * The application context for a session object may be retrieved 00080 * using ::pn_session_get_context. 00081 * 00082 * @param[in] session the session object 00083 * @param[in] context the application context 00084 */ 00085 PN_EXTERN void pn_session_set_context(pn_session_t *session, void *context); 00086 00087 /** 00088 * Get the endpoint state flags for a session. 00089 * 00090 * @param[in] session the session 00091 * @return the session's state flags 00092 */ 00093 PN_EXTERN pn_state_t pn_session_state(pn_session_t *session); 00094 00095 /** 00096 * Get additional error information associated with the session. 00097 * 00098 * Whenever a session operation fails (i.e. returns an error code), 00099 * additional error details can be obtained using this function. The 00100 * error object that is returned may also be used to clear the error 00101 * condition. 00102 * 00103 * The pointer returned by this operation is valid until the 00104 * session object is freed. 00105 * 00106 * @param[in] session the sesion object 00107 * @return the session's error object 00108 */ 00109 PN_EXTERN pn_error_t *pn_session_error(pn_session_t *session); 00110 00111 /** 00112 * Get the local condition associated with the session endpoint. 00113 * 00114 * The ::pn_condition_t object retrieved may be modified prior to 00115 * closing the session in order to indicate a particular condition 00116 * exists when the session closes. This is normally used to 00117 * communicate error conditions to the remote peer, however it may 00118 * also be used in non error cases. See ::pn_condition_t for more 00119 * details. 00120 * 00121 * The pointer returned by this operation is valid until the session 00122 * object is freed. 00123 * 00124 * @param[in] session the session object 00125 * @return the session's local condition object 00126 */ 00127 PN_EXTERN pn_condition_t *pn_session_condition(pn_session_t *session); 00128 00129 /** 00130 * Get the remote condition associated with the session endpoint. 00131 * 00132 * The ::pn_condition_t object retrieved may be examined in order to 00133 * determine whether the remote peer was indicating some sort of 00134 * exceptional condition when the remote session endpoint was 00135 * closed. The ::pn_condition_t object returned may not be modified. 00136 * 00137 * The pointer returned by this operation is valid until the 00138 * session object is freed. 00139 * 00140 * @param[in] session the session object 00141 * @return the session's remote condition object 00142 */ 00143 PN_EXTERN pn_condition_t *pn_session_remote_condition(pn_session_t *session); 00144 00145 /** 00146 * Get the parent connection for a session object. 00147 * 00148 * This operation retrieves the parent pn_connection_t object that 00149 * contains the given pn_session_t object. 00150 * 00151 * @param[in] session the session object 00152 * @return the parent connection object 00153 */ 00154 PN_EXTERN pn_connection_t *pn_session_connection(pn_session_t *session); 00155 00156 /** 00157 * Open a session. 00158 * 00159 * Once this operation has completed, the PN_LOCAL_ACTIVE state flag 00160 * will be set. 00161 * 00162 * @param[in] session a session object 00163 */ 00164 PN_EXTERN void pn_session_open(pn_session_t *session); 00165 00166 /** 00167 * Close a session. 00168 * 00169 * Once this operation has completed, the PN_LOCAL_CLOSED state flag 00170 * will be set. This may be called without calling 00171 * ::pn_session_open, in this case it is equivalent to calling 00172 * ::pn_session_open followed by ::pn_session_close. 00173 * 00174 * @param[in] session a session object 00175 */ 00176 PN_EXTERN void pn_session_close(pn_session_t *session); 00177 00178 /** 00179 * Get the incoming capacity of the session measured in bytes. 00180 * 00181 * The incoming capacity of a session determines how much incoming 00182 * message data the session will buffer. Note that if this value is 00183 * less than the negotiated frame size of the transport, it will be 00184 * rounded up to one full frame. 00185 * 00186 * @param[in] session the session object 00187 * @return the incoming capacity of the session in bytes 00188 */ 00189 PN_EXTERN size_t pn_session_get_incoming_capacity(pn_session_t *session); 00190 00191 /** 00192 * Set the incoming capacity for a session object. 00193 * 00194 * The incoming capacity of a session determines how much incoming 00195 * message data the session will buffer. Note that if this value is 00196 * less than the negotiated frame size of the transport, it will be 00197 * rounded up to one full frame. 00198 * 00199 * @param[in] session the session object 00200 * @param[in] capacity the incoming capacity for the session 00201 */ 00202 PN_EXTERN void pn_session_set_incoming_capacity(pn_session_t *session, size_t capacity); 00203 00204 /** 00205 * Get the number of outgoing bytes currently buffered by a session. 00206 * 00207 * @param[in] session a session object 00208 * @return the number of outgoing bytes currently buffered 00209 */ 00210 PN_EXTERN size_t pn_session_outgoing_bytes(pn_session_t *session); 00211 00212 /** 00213 * Get the number of incoming bytes currently buffered by a session. 00214 * 00215 * @param[in] session a session object 00216 * @return the number of incoming bytes currently buffered 00217 */ 00218 PN_EXTERN size_t pn_session_incoming_bytes(pn_session_t *session); 00219 00220 /** 00221 * Retrieve the first session from a given connection that matches the 00222 * specified state mask. 00223 * 00224 * Examines the state of each session owned by the connection, and 00225 * returns the first session that matches the given state mask. If 00226 * state contains both local and remote flags, then an exact match 00227 * against those flags is performed. If state contains only local or 00228 * only remote flags, then a match occurs if any of the local or 00229 * remote flags are set respectively. 00230 * 00231 * @param[in] connection to be searched for matching sessions 00232 * @param[in] state mask to match 00233 * @return the first session owned by the connection that matches the 00234 * mask, else NULL if no sessions match 00235 */ 00236 PN_EXTERN pn_session_t *pn_session_head(pn_connection_t *connection, pn_state_t state); 00237 00238 /** 00239 * Retrieve the next session from a given connection that matches the 00240 * specified state mask. 00241 * 00242 * When used with ::pn_session_head, application can access all 00243 * sessions on the connection that match the given state. See 00244 * ::pn_session_head for description of match behavior. 00245 * 00246 * @param[in] session the previous session obtained from 00247 * ::pn_session_head or ::pn_session_next 00248 * @param[in] state mask to match. 00249 * @return the next session owned by the connection that matches the 00250 * mask, else NULL if no sessions match 00251 */ 00252 PN_EXTERN pn_session_t *pn_session_next(pn_session_t *session, pn_state_t state); 00253 00254 /** @} 00255 */ 00256 00257 #ifdef __cplusplus 00258 } 00259 #endif 00260 00261 #endif /* session.h */