Qpid Proton C API  0.37.0
messenger.h
Go to the documentation of this file.
1 #ifndef PROTON_MESSENGER_H
2 #define PROTON_MESSENGER_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/message.h>
27 #include <proton/selectable.h>
28 #include <proton/link.h>
29 #include <proton/transport.h>
30 #include <proton/ssl.h>
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35 
154 typedef struct pn_messenger_t pn_messenger_t;
155 
159 typedef struct pn_subscription_t pn_subscription_t;
160 
165 typedef int64_t pn_tracker_t;
166 
171 typedef enum {
173  PN_STATUS_PENDING = 1,
181  PN_STATUS_SETTLED = 7
183 
193 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
194 PNX_EXTERN pn_messenger_t *pn_messenger(const char *name);
195 
202 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
203 PNX_EXTERN const char *pn_messenger_name(pn_messenger_t *messenger);
204 
214 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
215 PNX_EXTERN int pn_messenger_set_certificate(pn_messenger_t *messenger, const char *certificate);
216 
224 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
225 PNX_EXTERN const char *pn_messenger_get_certificate(pn_messenger_t *messenger);
226 
235 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
236 PNX_EXTERN int pn_messenger_set_private_key(pn_messenger_t *messenger, const char *private_key);
237 
244 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
245 PNX_EXTERN const char *pn_messenger_get_private_key(pn_messenger_t *messenger);
246 
255 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
256 PNX_EXTERN int pn_messenger_set_password(pn_messenger_t *messenger, const char *password);
257 
264 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
265 PNX_EXTERN const char *pn_messenger_get_password(pn_messenger_t *messenger);
266 
278 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
279 PNX_EXTERN int pn_messenger_set_trusted_certificates(pn_messenger_t *messenger, const char *cert_db);
280 
287 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
288 PNX_EXTERN const char *pn_messenger_get_trusted_certificates(pn_messenger_t *messenger);
289 
302 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
303 PNX_EXTERN int pn_messenger_set_timeout(pn_messenger_t *messenger, int timeout);
304 
313 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
314 PNX_EXTERN int pn_messenger_get_timeout(pn_messenger_t *messenger);
315 
322 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
323 PNX_EXTERN bool pn_messenger_is_blocking(pn_messenger_t *messenger);
324 
333 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
334 PNX_EXTERN int pn_messenger_set_blocking(pn_messenger_t *messenger, bool blocking);
335 
348 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
349 PNX_EXTERN bool pn_messenger_is_passive(pn_messenger_t *messenger);
350 
361 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
362 PNX_EXTERN int pn_messenger_set_passive(pn_messenger_t *messenger, bool passive);
363 
369 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
370 PNX_EXTERN void pn_messenger_free(pn_messenger_t *messenger);
371 
385 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
386 PNX_EXTERN int pn_messenger_errno(pn_messenger_t *messenger);
387 
399 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
401 
417 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
419 
430 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
431 PNX_EXTERN int pn_messenger_set_outgoing_window(pn_messenger_t *messenger, int window);
432 
451 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
453 
464 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
466  int window);
467 
476 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
477 PNX_EXTERN int pn_messenger_start(pn_messenger_t *messenger);
478 
493 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
494 PNX_EXTERN int pn_messenger_stop(pn_messenger_t *messenger);
495 
503 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
504 PNX_EXTERN bool pn_messenger_stopped(pn_messenger_t *messenger);
505 
513 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
514 PNX_EXTERN pn_subscription_t *pn_messenger_subscribe(pn_messenger_t *messenger, const char *source);
515 
526 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
527 PNX_EXTERN pn_subscription_t *
528 pn_messenger_subscribe_ttl(pn_messenger_t *messenger, const char *source,
529  pn_seconds_t timeout);
530 
540 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
542  const char *address, bool sender);
543 
552 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
554 
561 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
562 PNX_EXTERN void pn_subscription_set_context(pn_subscription_t *sub, void *context);
563 
570 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
571 PNX_EXTERN const char *pn_subscription_address(pn_subscription_t *sub);
572 
583 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
584 PNX_EXTERN int pn_messenger_put(pn_messenger_t *messenger, pn_message_t *msg);
585 
597 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
599 
611 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
613  pn_tracker_t tracker);
614 
627 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
628 PNX_EXTERN bool pn_messenger_buffered(pn_messenger_t *messenger, pn_tracker_t tracker);
629 
642 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
643 PNX_EXTERN int pn_messenger_settle(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
644 
658 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
660 
671 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
672 PNX_EXTERN int pn_messenger_work(pn_messenger_t *messenger, int timeout);
673 
685 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
686 PNX_EXTERN int pn_messenger_interrupt(pn_messenger_t *messenger);
687 
720 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
721 PNX_EXTERN int pn_messenger_send(pn_messenger_t *messenger, int n);
722 
747 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
748 PNX_EXTERN int pn_messenger_recv(pn_messenger_t *messenger, int limit);
749 
760 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
761 PNX_EXTERN int pn_messenger_receiving(pn_messenger_t *messenger);
762 
777 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
778 PNX_EXTERN int pn_messenger_get(pn_messenger_t *messenger, pn_message_t *message);
779 
793 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
795 
805 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
807 
811 #define PN_CUMULATIVE (0x1)
812 
834 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
835 PNX_EXTERN int pn_messenger_accept(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
836 
858 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
859 PNX_EXTERN int pn_messenger_reject(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
860 
868 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
870  pn_tracker_t tracker);
871 
879 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
880 PNX_EXTERN int pn_messenger_outgoing(pn_messenger_t *messenger);
881 
888 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
889 PNX_EXTERN int pn_messenger_incoming(pn_messenger_t *messenger);
890 
953 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
954 PNX_EXTERN int pn_messenger_route(pn_messenger_t *messenger, const char *pattern,
955  const char *address);
956 
979 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
980 PNX_EXTERN int pn_messenger_rewrite(pn_messenger_t *messenger, const char *pattern,
981  const char *address);
982 
1009 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
1010 PNX_EXTERN pn_selectable_t *pn_messenger_selectable(pn_messenger_t *messenger);
1011 
1018 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
1020 
1021 #define PN_FLAGS_CHECK_ROUTES \
1022  (0x1)
1026 #define PN_FLAGS_ALLOW_INSECURE_MECHS \
1027  (0x2)
1039 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
1040 PNX_EXTERN int pn_messenger_set_flags(pn_messenger_t *messenger,
1041  const int flags);
1042 
1049 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
1050 PNX_EXTERN int pn_messenger_get_flags(pn_messenger_t *messenger);
1051 
1058 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
1060  const pn_snd_settle_mode_t mode);
1061 
1068 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
1070  const pn_rcv_settle_mode_t mode);
1071 
1078 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
1079 PNX_EXTERN void pn_messenger_set_tracer(pn_messenger_t *messenger,
1080  pn_tracer_t tracer);
1081 
1089 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
1090 PNX_EXTERN pn_millis_t
1092  const char *address);
1093 
1103 PN_DEPRECATED("Use the Proactor API or Qpid Proton C++")
1104 PNX_EXTERN int
1106  const pn_ssl_verify_mode_t mode);
1107 
1112 #ifdef __cplusplus
1113 }
1114 #endif
1115 
1116 #endif /* messenger.h */
int64_t pn_timestamp_t
A 64-bit timestamp in milliseconds since the Unix epoch.
Definition: types.h:170
uint32_t pn_millis_t
A span of time in milliseconds.
Definition: types.h:149
uint32_t pn_seconds_t
A span of time in seconds.
Definition: types.h:163
struct pn_delivery_t pn_delivery_t
An AMQP Delivery object.
Definition: types.h:405
struct pn_error_t pn_error_t
An int error code and some string text to describe the error.
Definition: error.h:44
struct pn_message_t pn_message_t
An AMQP Message object.
Definition: message.h:51
pn_tracker_t pn_messenger_outgoing_tracker(pn_messenger_t *messenger)
Get a tracker for the outgoing message most recently given to pn_messenger_put.
pn_error_t * pn_messenger_error(pn_messenger_t *messenger)
Get a messenger's error object.
int pn_messenger_set_timeout(pn_messenger_t *messenger, int timeout)
Set the default timeout for a messenger.
int pn_messenger_set_private_key(pn_messenger_t *messenger, const char *private_key)
Set path to the private key that was used to sign the certificate.
int pn_messenger_outgoing(pn_messenger_t *messenger)
Get the number of messages in the outgoing message queue of a messenger.
int pn_messenger_get_timeout(pn_messenger_t *messenger)
Gets the timeout for a messenger object.
struct pn_messenger_t pn_messenger_t
A pn_messenger_t provides a high level interface for sending and receiving messages (See pn_message_t...
Definition: messenger.h:154
int pn_messenger_accept(pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
Signal successful processing of message(s).
bool pn_messenger_buffered(pn_messenger_t *messenger, pn_tracker_t tracker)
Check if the delivery associated with a given tracker is still waiting to be sent.
int pn_messenger_recv(pn_messenger_t *messenger, int limit)
Retrieve messages into a messenger's incoming queue.
const char * pn_messenger_get_certificate(pn_messenger_t *messenger)
Get the certificate path.
pn_timestamp_t pn_messenger_deadline(pn_messenger_t *messenger)
Get the nearest deadline for selectables associated with a messenger.
int pn_messenger_reject(pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
Signal unsuccessful processing of message(s).
pn_status_t
Describes all the possible states for a message associated with a given tracker.
Definition: messenger.h:171
void pn_subscription_set_context(pn_subscription_t *sub, void *context)
Set an application context for a subscription.
const char * pn_messenger_get_password(pn_messenger_t *messenger)
Gets the private key file password for a messenger.
int pn_messenger_incoming(pn_messenger_t *messenger)
Get the number of messages in the incoming message queue of a messenger.
int pn_messenger_get_incoming_window(pn_messenger_t *messenger)
Get the size of a messenger's incoming window.
int pn_messenger_settle(pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
Frees a Messenger from tracking the status associated with a given tracker.
int pn_messenger_work(pn_messenger_t *messenger, int timeout)
Sends or receives any outstanding messages queued for a messenger.
pn_subscription_t * pn_messenger_subscribe_ttl(pn_messenger_t *messenger, const char *source, pn_seconds_t timeout)
Subscribes a messenger to messages from the specified source with the given timeout for the subscript...
void pn_messenger_free(pn_messenger_t *messenger)
Frees a Messenger.
int pn_messenger_set_ssl_peer_authentication_mode(pn_messenger_t *messenger, const pn_ssl_verify_mode_t mode)
Sets the SSL peer authentication mode required when a trust certificate is used.
bool pn_messenger_is_passive(pn_messenger_t *messenger)
Check if a messenger is in passive mode.
pn_delivery_t * pn_messenger_delivery(pn_messenger_t *messenger, pn_tracker_t tracker)
Get delivery information about a delivery.
int pn_messenger_set_password(pn_messenger_t *messenger, const char *password)
Sets the private key password for a messenger.
void pn_messenger_set_tracer(pn_messenger_t *messenger, pn_tracer_t tracer)
Set the tracer associated with a messenger.
int pn_messenger_route(pn_messenger_t *messenger, const char *pattern, const char *address)
Adds a routing rule to a Messenger's internal routing table.
int pn_messenger_start(pn_messenger_t *messenger)
Currently a no-op placeholder.
const char * pn_messenger_name(pn_messenger_t *messenger)
Get the name of a messenger.
pn_link_t * pn_messenger_get_link(pn_messenger_t *messenger, const char *address, bool sender)
Get a link based on link name and whether the link is a sender or receiver.
int pn_messenger_set_snd_settle_mode(pn_messenger_t *messenger, const pn_snd_settle_mode_t mode)
Set the local sender settle mode for the underlying link.
pn_selectable_t * pn_messenger_selectable(pn_messenger_t *messenger)
Extract selectables from a passive messenger.
void * pn_subscription_get_context(pn_subscription_t *sub)
Get a subscription's application context.
const char * pn_subscription_address(pn_subscription_t *sub)
Get the source address of a subscription.
const char * pn_messenger_get_trusted_certificates(pn_messenger_t *messenger)
Gets the trusted certificates database for a messenger.
int pn_messenger_set_outgoing_window(pn_messenger_t *messenger, int window)
Set the size of a messenger's outgoing window.
pn_millis_t pn_messenger_get_remote_idle_timeout(pn_messenger_t *messenger, const char *address)
Gets the remote idle timeout for the specified remote service address.
int pn_messenger_interrupt(pn_messenger_t *messenger)
Interrupt a messenger object that may be blocking in another thread.
int pn_messenger_get_flags(pn_messenger_t *messenger)
Gets the flags for a Messenger.
int pn_messenger_get(pn_messenger_t *messenger, pn_message_t *message)
Get the next message from the head of a messenger's incoming queue.
int64_t pn_tracker_t
Trackers provide a lightweight handle used to track the status of incoming and outgoing deliveries.
Definition: messenger.h:165
const char * pn_messenger_get_private_key(pn_messenger_t *messenger)
Gets the private key file for a messenger.
struct pn_subscription_t pn_subscription_t
A subscription is a request for incoming messages.
Definition: messenger.h:159
pn_messenger_t * pn_messenger(const char *name)
Construct a new pn_messenger_t with the given name.
int pn_messenger_get_outgoing_window(pn_messenger_t *messenger)
Get the size of a messenger's outgoing window.
pn_subscription_t * pn_messenger_subscribe(pn_messenger_t *messenger, const char *source)
Subscribes a messenger to messages from the specified source.
int pn_messenger_rewrite(pn_messenger_t *messenger, const char *pattern, const char *address)
Rewrite message addresses prior to transmission.
int pn_messenger_set_passive(pn_messenger_t *messenger, bool passive)
Set the passive mode for a messenger.
int pn_messenger_set_flags(pn_messenger_t *messenger, const int flags)
Sets control flags to enable additional function for the Messenger.
int pn_messenger_errno(pn_messenger_t *messenger)
Get the code for a messenger's most recent error.
pn_status_t pn_messenger_status(pn_messenger_t *messenger, pn_tracker_t tracker)
Track the status of a delivery.
int pn_messenger_set_certificate(pn_messenger_t *messenger, const char *certificate)
Sets the path that will be used to get the certificate that will be used to identify this messenger t...
int pn_messenger_set_trusted_certificates(pn_messenger_t *messenger, const char *cert_db)
Sets the trusted certificates database for a messenger.
int pn_messenger_stop(pn_messenger_t *messenger)
Stops a messenger.
int pn_messenger_set_incoming_window(pn_messenger_t *messenger, int window)
Set the size of a messenger's incoming window.
bool pn_messenger_stopped(pn_messenger_t *messenger)
Returns true if a messenger is in the stopped state.
int pn_messenger_send(pn_messenger_t *messenger, int n)
Send messages from a messenger's outgoing queue.
pn_subscription_t * pn_messenger_incoming_subscription(pn_messenger_t *messenger)
Get the subscription of the message most recently retrieved by pn_messenger_get().
pn_link_t * pn_messenger_tracker_link(pn_messenger_t *messenger, pn_tracker_t tracker)
Get link for the message referenced by the given tracker.
int pn_messenger_set_blocking(pn_messenger_t *messenger, bool blocking)
Enable or disable blocking behavior for a messenger during calls to pn_messenger_send and pn_messenge...
int pn_messenger_set_rcv_settle_mode(pn_messenger_t *messenger, const pn_rcv_settle_mode_t mode)
Set the local receiver settle mode for the underlying link.
int pn_messenger_receiving(pn_messenger_t *messenger)
Get the capacity of the incoming message queue of a messenger.
bool pn_messenger_is_blocking(pn_messenger_t *messenger)
Check if a messenger is in blocking mode.
pn_tracker_t pn_messenger_incoming_tracker(pn_messenger_t *messenger)
Get a tracker for the message most recently retrieved by pn_messenger_get().
int pn_messenger_put(pn_messenger_t *messenger, pn_message_t *msg)
Puts a message onto the messenger's outgoing queue.
@ PN_STATUS_UNKNOWN
The tracker is unknown.
Definition: messenger.h:172
@ PN_STATUS_SETTLED
The remote party has settled the message.
Definition: messenger.h:181
@ PN_STATUS_ABORTED
The message was aborted.
Definition: messenger.h:180
@ PN_STATUS_PENDING
The message is in flight.
Definition: messenger.h:173
@ PN_STATUS_RELEASED
The message was released.
Definition: messenger.h:178
@ PN_STATUS_ACCEPTED
The message was accepted.
Definition: messenger.h:176
@ PN_STATUS_MODIFIED
The message was modified.
Definition: messenger.h:179
@ PN_STATUS_REJECTED
The message was rejected.
Definition: messenger.h:177
pn_ssl_verify_mode_t
Determines the level of peer validation.
Definition: ssl.h:200
void(* pn_tracer_t)(pn_transport_t *transport, const char *message)
Callback for customizing logging behaviour.
Definition: transport.h:66
A mutable holder of application content.
SSL secure transport layer.
A network channel supporting an AMQP connection.