00001 #ifndef PROTON_MESSENGER_H 00002 #define PROTON_MESSENGER_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/message.h> 00027 00028 #ifdef __cplusplus 00029 extern "C" { 00030 #endif 00031 00032 /** @file 00033 * The messenger API provides a high level interface for sending and 00034 * receiving AMQP messages. 00035 */ 00036 00037 typedef struct pn_messenger_t pn_messenger_t; /**< Messenger*/ 00038 typedef struct pn_subscription_t pn_subscription_t; /**< Subscription*/ 00039 typedef int64_t pn_tracker_t; 00040 00041 typedef enum { 00042 PN_ACCEPT_MODE_AUTO, 00043 PN_ACCEPT_MODE_MANUAL 00044 } pn_accept_mode_t; 00045 00046 typedef enum { 00047 PN_STATUS_UNKNOWN = 0, 00048 PN_STATUS_PENDING = 1, 00049 PN_STATUS_ACCEPTED = 2, 00050 PN_STATUS_REJECTED = 3 00051 } pn_status_t; 00052 00053 /** Construct a new Messenger with the given name. The name is global. 00054 * If a NULL name is supplied, a UUID based name will be chosen. 00055 * 00056 * @param[in] name the name of the messenger or NULL 00057 * 00058 * @return pointer to a new Messenger 00059 */ 00060 PN_EXTERN pn_messenger_t *pn_messenger(const char *name); 00061 00062 /** Retrieves the name of a Messenger. 00063 * 00064 * @param[in] messenger the messenger 00065 * 00066 * @return the name of the messenger 00067 */ 00068 PN_EXTERN const char *pn_messenger_name(pn_messenger_t *messenger); 00069 00070 /** Sets the certificate file for a Messenger. 00071 * 00072 * @param[in] messenger the messenger 00073 * @param[in] certificate a path to a certificate file 00074 * 00075 * @return an error code of zero if there is no error 00076 */ 00077 PN_EXTERN int pn_messenger_set_certificate(pn_messenger_t *messenger, const char *certificate); 00078 00079 /** Gets the certificate file fora Messenger. 00080 * 00081 * @param[in] messenger the messenger 00082 * @return the certificate file path 00083 */ 00084 PN_EXTERN const char *pn_messenger_get_certificate(pn_messenger_t *messenger); 00085 00086 /** Sets the private key file for a Messenger. 00087 * 00088 * @param[in] messenger the Messenger 00089 * @param[in] private_key a path to a private key file 00090 * 00091 * @return an error code of zero if there is no error 00092 */ 00093 PN_EXTERN int pn_messenger_set_private_key(pn_messenger_t *messenger, const char *private_key); 00094 00095 /** Gets the private key file for a Messenger. 00096 * 00097 * @param[in] messenger the messenger 00098 * @return the private key file path 00099 */ 00100 PN_EXTERN const char *pn_messenger_get_private_key(pn_messenger_t *messenger); 00101 00102 /** Sets the private key password for a Messenger. 00103 * 00104 * @param[in] messenger the messenger 00105 * @param[in] password the password for the private key file 00106 * 00107 * @return an error code of zero if there is no error 00108 */ 00109 PN_EXTERN int pn_messenger_set_password(pn_messenger_t *messenger, const char *password); 00110 00111 /** Gets the private key file password for a Messenger. 00112 * 00113 * @param[in] messenger the messenger 00114 * @return password for the private key file 00115 */ 00116 PN_EXTERN const char *pn_messenger_get_password(pn_messenger_t *messenger); 00117 00118 /** Sets the trusted certificates database for a Messenger. 00119 * 00120 * @param[in] messenger the messenger 00121 * @param[in] cert_db a path to the certificates database 00122 * 00123 * @return an error code of zero if there is no error 00124 */ 00125 PN_EXTERN int pn_messenger_set_trusted_certificates(pn_messenger_t *messenger, const char *cert_db); 00126 00127 /** Gets the trusted certificates database for a Messenger. 00128 * 00129 * @param[in] messenger the messenger 00130 * @return path to the trusted certificates database 00131 */ 00132 PN_EXTERN const char *pn_messenger_get_trusted_certificates(pn_messenger_t *messenger); 00133 00134 /** Sets the timeout for a Messenger. A negative timeout means 00135 * infinite. 00136 * 00137 * @param[in] messenger the messenger 00138 * @param[in] timeout the new timeout for the messenger, in milliseconds 00139 * 00140 * @return an error code or zero if there is no error 00141 */ 00142 PN_EXTERN int pn_messenger_set_timeout(pn_messenger_t *messenger, int timeout); 00143 00144 /** Retrieves the timeout for a Messenger. 00145 * 00146 * @param[in] messenger the messenger 00147 * 00148 * @return the timeout for the messenger, in milliseconds 00149 */ 00150 PN_EXTERN int pn_messenger_get_timeout(pn_messenger_t *messenger); 00151 00152 /** Frees a Messenger. 00153 * 00154 * @param[in] messenger the messenger to free, no longer valid on 00155 * return 00156 */ 00157 PN_EXTERN void pn_messenger_free(pn_messenger_t *messenger); 00158 00159 /** Returns the error code for the Messenger. 00160 * 00161 * @param[in] messenger the messenger to check for errors 00162 * 00163 * @return an error code or zero if there is no error 00164 * @see error.h 00165 */ 00166 PN_EXTERN int pn_messenger_errno(pn_messenger_t *messenger); 00167 00168 /** Returns the error info for a Messenger. 00169 * 00170 * @param[in] messenger the messenger to check for errors 00171 * 00172 * @return a descriptive error message or NULL if no error has 00173 * occurred 00174 */ 00175 PN_EXTERN const char *pn_messenger_error(pn_messenger_t *messenger); 00176 00177 /** Gets the accept mode for a Messenger. @see 00178 * ::pn_messenger_set_accept_mode 00179 * 00180 * @param[in] messenger the messenger 00181 * 00182 * @return one of PN_ACCEPT_MODE_AUTO or PN_ACCEPT_MODE_MANUAL 00183 */ 00184 PN_EXTERN pn_accept_mode_t pn_messenger_get_accept_mode(pn_messenger_t *messenger); 00185 00186 /** Set the accept mode for a Messenger. If set to 00187 * PN_ACCEPT_MODE_AUTO, the messenger will automatically accept every 00188 * message as it is returned by pn_messenger_get(). If set to 00189 * PN_ACCEPT_MODE_MANUAL, incoming messages must be manually accepted 00190 * or rejected (either individually or cumulatively) via 00191 * pn_messenger_accept() and/or pn_messenger_reject(). 00192 * 00193 * @param[in] messenger the messenger to set the accept mode for 00194 * @param[in] mode one of PN_ACCEPT_MODE_AUTO or PN_ACCEPT_MODE_MANUAL 00195 * 00196 * @return an error code or zero on success 00197 * @see error.h 00198 */ 00199 PN_EXTERN int pn_messenger_set_accept_mode(pn_messenger_t *messenger, pn_accept_mode_t mode); 00200 00201 /** Gets the outgoing window for a Messenger. @see 00202 * ::pn_messenger_set_outgoing_window 00203 * 00204 * @param[in] messenger the messenger 00205 * 00206 * @return the outgoing window 00207 */ 00208 PN_EXTERN int pn_messenger_get_outgoing_window(pn_messenger_t *messenger); 00209 00210 /** Sets the outgoing window for a Messenger. If the outgoing window 00211 * is set to a positive value, then after each call to 00212 * pn_messenger_send, the Messenger will track the status of that 00213 * many deliveries. @see ::pn_messenger_status 00214 * 00215 * @param[in] messenger the Messenger 00216 * @param[in] window the number of deliveries to track 00217 * 00218 * @return an error or zero on success 00219 * @see error.h 00220 */ 00221 PN_EXTERN int pn_messenger_set_outgoing_window(pn_messenger_t *messenger, int window); 00222 00223 /** Gets the incoming window for a Messenger. @see 00224 * ::pn_messenger_set_incoming_window 00225 * 00226 * @param[in] messenger the Messenger 00227 * 00228 * @return the incoming window 00229 */ 00230 PN_EXTERN int pn_messenger_get_incoming_window(pn_messenger_t *messenger); 00231 00232 /** Sets the incoming window for a Messenger. If the incoming window 00233 * is set to a positive value, then after each call to 00234 * pn_messenger_accept or pn_messenger_reject, the Messenger will 00235 * track the status of that many deliveries. @see 00236 * ::pn_messenger_status 00237 * 00238 * @param[in] messenger the Messenger 00239 * @param[in] window the number of deliveries to track 00240 * 00241 * @return an error or zero on success 00242 * @see error.h 00243 */ 00244 PN_EXTERN int pn_messenger_set_incoming_window(pn_messenger_t *messenger, int window); 00245 00246 /** Starts a messenger. A messenger cannot send or recv messages until 00247 * it is started. 00248 * 00249 * @param[in] messenger the messenger to start 00250 * 00251 * @return an error code or zero on success 00252 * @see error.h 00253 */ 00254 PN_EXTERN int pn_messenger_start(pn_messenger_t *messenger); 00255 00256 /** Stops a messenger. A messenger cannot send or recv messages when 00257 * it is stopped. 00258 * 00259 * @param[in] messenger the messenger to stop 00260 * 00261 * @return an error code or zero on success 00262 * @see error.h 00263 */ 00264 PN_EXTERN int pn_messenger_stop(pn_messenger_t *messenger); 00265 00266 /** Subscribes a messenger to messages from the specified source. 00267 * 00268 * @param[in] messenger the messenger to subscribe 00269 * @param[in] source 00270 * 00271 * @return a subscription 00272 */ 00273 PN_EXTERN pn_subscription_t *pn_messenger_subscribe(pn_messenger_t *messenger, const char *source); 00274 00275 PN_EXTERN void *pn_subscription_get_context(pn_subscription_t *sub); 00276 00277 PN_EXTERN void pn_subscription_set_context(pn_subscription_t *sub, void *context); 00278 00279 /** Puts a message on the outgoing message queue for a messenger. 00280 * 00281 * @param[in] messenger the messenger 00282 * @param[in] msg the message to put on the outgoing queue 00283 * 00284 * @return an error code or zero on success 00285 * @see error.h 00286 */ 00287 PN_EXTERN int pn_messenger_put(pn_messenger_t *messenger, pn_message_t *msg); 00288 00289 /** Gets the last known remote state of the delivery associated with 00290 * the given tracker. 00291 * 00292 * @param[in] messenger the messenger 00293 * @param[in] tracker the tracker identify the delivery 00294 * 00295 * @return a status code for the delivery 00296 */ 00297 PN_EXTERN pn_status_t pn_messenger_status(pn_messenger_t *messenger, pn_tracker_t tracker); 00298 00299 /** Frees a Messenger from tracking the status associated with a given 00300 * tracker. Use the PN_CUMULATIVE flag to indicate everything up to 00301 * (and including) the given tracker. 00302 * 00303 * @param[in] messenger the Messenger 00304 * @param[in] tracker identifies a delivery 00305 * @param[in] flags 0 or PN_CUMULATIVE 00306 * 00307 * @return an error code or zero on success 00308 * @see error.h 00309 */ 00310 PN_EXTERN int pn_messenger_settle(pn_messenger_t *messenger, pn_tracker_t tracker, int flags); 00311 00312 /** Gets the tracker for the message most recently provided to 00313 * pn_messenger_put. 00314 * 00315 * @param[in] messenger the messenger 00316 * 00317 * @return a pn_tracker_t or an undefined value if pn_messenger_get 00318 * has never been called for the given messenger 00319 */ 00320 PN_EXTERN pn_tracker_t pn_messenger_outgoing_tracker(pn_messenger_t *messenger); 00321 00322 /** Sends any messages in the outgoing message queue for a messenger. 00323 * This will block until the messages have been sent. 00324 * 00325 * @param[in] messenger the messager 00326 * 00327 * @return an error code or zero on success 00328 * @see error.h 00329 */ 00330 PN_EXTERN int pn_messenger_send(pn_messenger_t *messenger); 00331 00332 /** Receives up to n messages into the incoming message queue of a 00333 * messenger. If n is -1, Messenger will be able to receive as many 00334 * messages as it can buffer internally. Blocks until at least one 00335 * message is available in the incoming queue. 00336 * 00337 * @param[in] messenger the messenger 00338 * @param[in] n the maximum number of messages to receive or -1 to to 00339 * receive as many messages as it can buffer internally. 00340 * 00341 * @return an error code or zero on success 00342 * @see error.h 00343 */ 00344 PN_EXTERN int pn_messenger_recv(pn_messenger_t *messenger, int n); 00345 00346 /** Gets a message from the head of the incoming message queue of a 00347 * messenger. 00348 * 00349 * @param[in] messenger the messenger 00350 * @param[out] msg upon return contains the message from the head of the queue 00351 * 00352 * @return an error code or zero on success 00353 * @see error.h 00354 */ 00355 PN_EXTERN int pn_messenger_get(pn_messenger_t *messenger, pn_message_t *msg); 00356 00357 /** Gets the tracker for the message most recently fetched by 00358 * pn_messenger_get. 00359 * 00360 * @param[in] messenger the messenger 00361 * 00362 * @return a pn_tracker_t or an undefined value if pn_messenger_get 00363 * has never been called for the given messenger 00364 */ 00365 PN_EXTERN pn_tracker_t pn_messenger_incoming_tracker(pn_messenger_t *messenger); 00366 00367 PN_EXTERN pn_subscription_t *pn_messenger_incoming_subscription(pn_messenger_t *messenger); 00368 00369 #define PN_CUMULATIVE (0x1) 00370 00371 /** Accepts the incoming messages identified by the tracker. Use the 00372 * PN_CUMULATIVE flag to accept everything prior to the supplied 00373 * tracker. 00374 * 00375 * @param[in] messenger the messenger 00376 * @param[in] tracker an incoming tracker 00377 * @param[in] flags 0 or PN_CUMULATIVE 00378 * 00379 * @return an error code or zero on success 00380 * @see error.h 00381 */ 00382 PN_EXTERN int pn_messenger_accept(pn_messenger_t *messenger, pn_tracker_t tracker, int flags); 00383 00384 /** Rejects the incoming messages identified by the tracker. Use the 00385 * PN_CUMULATIVE flag to reject everything prior to the supplied 00386 * tracker. 00387 * 00388 * @param[in] messenger the Messenger 00389 * @param[in] tracker an incoming tracker 00390 * @param[in] flags 0 or PN_CUMULATIVE 00391 * 00392 * @return an error code or zero on success 00393 * @see error.h 00394 */ 00395 PN_EXTERN int pn_messenger_reject(pn_messenger_t *messenger, pn_tracker_t tracker, int flags); 00396 00397 /** Returns the number of messages in the outgoing message queue of a messenger. 00398 * 00399 * @param[in] messenger the Messenger 00400 * 00401 * @return the outgoing queue depth 00402 */ 00403 PN_EXTERN int pn_messenger_outgoing(pn_messenger_t *messenger); 00404 00405 /** Returns the number of messages in the incoming message queue of a messenger. 00406 * 00407 * @param[in] messenger the Messenger 00408 * 00409 * @return the incoming queue depth 00410 */ 00411 PN_EXTERN int pn_messenger_incoming(pn_messenger_t *messenger); 00412 00413 #ifdef __cplusplus 00414 } 00415 #endif 00416 00417 #endif /* messenger.h */