This file is indexed.

/usr/include/proton/messenger.h is in libqpid-proton8-dev 0.14.0-5.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
#ifndef PROTON_MESSENGER_H
#define PROTON_MESSENGER_H 1

/*
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 */

#include <proton/import_export.h>
#include <proton/message.h>
#include <proton/selectable.h>
#include <proton/condition.h>
#include <proton/terminus.h>
#include <proton/link.h>
#include <proton/transport.h>
#include <proton/ssl.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @file
 *
 * The messenger API provides a high level interface for sending and
 * receiving AMQP messages.
 *
 * @defgroup messenger Messenger
 * @{
 */

/**
 * A ::pn_messenger_t provides a high level interface for sending and
 * receiving messages (See ::pn_message_t).
 *
 * Every messenger contains a single logical queue of incoming
 * messages and a single logical queue of outgoing messages. The
 * messages in these queues may be destined for, or originate from, a
 * variety of addresses.
 *
 * The messenger interface is single-threaded. All methods except one
 * (::pn_messenger_interrupt()) are intended to be used by one thread
 * at a time.
 *
 *
 * Address Syntax
 * ==============
 *
 * An address has the following form::
 *
 *   [ amqp[s]:// ] [user[:password]@] domain [/[name]]
 *
 * Where domain can be one of::
 *
 *   host | host:port | ip | ip:port | name
 *
 * The following are valid examples of addresses:
 *
 *  - example.org
 *  - example.org:1234
 *  - amqp://example.org
 *  - amqps://example.org
 *  - example.org/incoming
 *  - amqps://example.org/outgoing
 *  - amqps://fred:trustno1@example.org
 *  - 127.0.0.1:1234
 *  - amqps://127.0.0.1:1234
 *
 * Sending & Receiving Messages
 * ============================
 *
 * The messenger API works in conjuction with the ::pn_message_t API.
 * A ::pn_message_t is a mutable holder of message content.
 *
 * The ::pn_messenger_put() operation copies content from the supplied
 * ::pn_message_t to the outgoing queue, and may send queued messages
 * if it can do so without blocking. The ::pn_messenger_send()
 * operation blocks until it has sent the requested number of
 * messages, or until a timeout interrupts the attempt.
 *
 *
 *   pn_messenger_t *messenger = pn_messenger(NULL);
 *   pn_message_t *message = pn_message();
 *   char subject[1024];
 *   for (int i = 0; i < 3; i++) {
 *     pn_message_set_address(message, "amqp://host/queue");
 *     sprintf(subject, "Hello World! %i", i);
 *     pn_message_set_subject(message, subject);
 *     pn_messenger_put(messenger, message)
 *   pn_messenger_send(messenger);
 *
 * Similarly, the ::pn_messenger_recv() method receives messages into
 * the incoming queue, and may block as it attempts to receive up to
 * the requested number of messages, or until the timeout is reached.
 * It may receive fewer than the requested number. The
 * ::pn_messenger_get() method pops the eldest message off the
 * incoming queue and copies its content into the supplied
 * ::pn_message_t object. It will not block.
 *
 *
 *   pn_messenger_t *messenger = pn_messenger(NULL);
 *   pn_message_t *message = pn_message()
 *   pn_messenger_recv(messenger):
 *   while (pn_messenger_incoming(messenger) > 0) {
 *     pn_messenger_get(messenger, message);
 *     printf("%s", message.subject);
 *   }
 *
 *   Output:
 *     Hello World 0
 *     Hello World 1
 *     Hello World 2
 *
 * The blocking flag allows you to turn off blocking behavior
 * entirely, in which case ::pn_messenger_send() and
 * ::pn_messenger_recv() will do whatever they can without blocking,
 * and then return. You can then look at the number of incoming and
 * outgoing messages to see how much outstanding work still remains.
 *
 * Authentication Mechanims
 * ========================
 *
 * The messenger API authenticates using some specific mechanisms. In prior versions
 * of Proton the only authentication mechanism available was the PLAIN mechanism
 * which transports the user's password over the network unencrypted. The Proton versions
 * 0.10 and newer support other more secure mechanisms which avoid sending the users's
 * password over the network unencrypted. For backwards compatibility the 0.10 version
 * of the messenger API will also allow the use of the unencrypted PLAIN mechanism. From the
 * 0.11 version and onwards you will need to set the flag PN_FLAGS_ALLOW_INSECURE_MECHS to
 * carry on using the unencrypted PLAIN mechanism.
 *
 * The code for this looks like:
 *
 *   ...
 *   pn_messenger_set_flags(messenger, PN_FLAGS_ALLOW_INSECURE_MECHS);
 *   ...
 *
 * Note that the use of the PLAIN mechanism over an SSL connection is allowed as the
 * password is not sent unencrypted.
 */
typedef struct pn_messenger_t pn_messenger_t;

/**
 * A subscription is a request for incoming messages.
 *
 * @todo currently the subscription API is under developed, this
 * should allow more explicit control over subscription properties and
 * behaviour
 */
typedef struct pn_subscription_t pn_subscription_t;

/**
 * Trackers provide a lightweight handle used to track the status of
 * incoming and outgoing deliveries.
 */
typedef int64_t pn_tracker_t;

/**
 * Describes all the possible states for a message associated with a
 * given tracker.
 */
typedef enum {
  PN_STATUS_UNKNOWN = 0, /**< The tracker is unknown. */
  PN_STATUS_PENDING = 1, /**< The message is in flight. For outgoing
                            messages, use ::pn_messenger_buffered to
                            see if it has been sent or not. */
  PN_STATUS_ACCEPTED = 2, /**< The message was accepted. */
  PN_STATUS_REJECTED = 3, /**< The message was rejected. */
  PN_STATUS_RELEASED = 4, /**< The message was released. */
  PN_STATUS_MODIFIED = 5, /**< The message was modified. */
  PN_STATUS_ABORTED = 6, /**< The message was aborted. */
  PN_STATUS_SETTLED = 7 /**< The remote party has settled the message. */
} pn_status_t;

/**
 * Construct a new ::pn_messenger_t with the given name. The name is
 * global. If a NULL name is supplied, a UUID based name will be
 * chosen.
 *
 * @param[in] name the name of the messenger or NULL
 *
 * @return pointer to a new ::pn_messenger_t
 */
PN_EXTERN pn_messenger_t *pn_messenger(const char *name);

/**
 * Get the name of a messenger.
 *
 * @param[in] messenger a messenger object
 * @return the name of the messenger
 */
PN_EXTERN const char *pn_messenger_name(pn_messenger_t *messenger);

/**
 * Sets the path that will be used to get the certificate that will be
 * used to identify this messenger to its peers. The validity of the
 * path is not checked by this function.
 *
 * @param[in] messenger the messenger
 * @param[in] certificate a path to a certificate file
 * @return an error code of zero if there is no error
 */
PN_EXTERN int pn_messenger_set_certificate(pn_messenger_t *messenger, const char *certificate);

/**
 * Get the certificate path. This value may be set by
 * pn_messenger_set_certificate. The default certificate path is null.
 *
 * @param[in] messenger the messenger
 * @return the certificate file path
 */
PN_EXTERN const char *pn_messenger_get_certificate(pn_messenger_t *messenger);

/**
 * Set path to the private key that was used to sign the certificate.
 * See ::pn_messenger_set_certificate
 *
 * @param[in] messenger a messenger object
 * @param[in] private_key a path to a private key file
 * @return an error code of zero if there is no error
 */
PN_EXTERN int pn_messenger_set_private_key(pn_messenger_t *messenger, const char *private_key);

/**
 * Gets the private key file for a messenger.
 *
 * @param[in] messenger a messenger object
 * @return the messenger's private key file path
 */
PN_EXTERN const char *pn_messenger_get_private_key(pn_messenger_t *messenger);

/**
 * Sets the private key password for a messenger.
 *
 * @param[in] messenger a messenger object
 * @param[in] password the password for the private key file
 *
 * @return an error code of zero if there is no error
 */
PN_EXTERN int pn_messenger_set_password(pn_messenger_t *messenger, const char *password);

/**
 * Gets the private key file password for a messenger.
 *
 * @param[in] messenger a messenger object
 * @return password for the private key file
 */
PN_EXTERN const char *pn_messenger_get_password(pn_messenger_t *messenger);

/**
 * Sets the trusted certificates database for a messenger.
 *
 * The messenger will use this database to validate the certificate
 * provided by the peer.
 *
 * @param[in] messenger a messenger object
 * @param[in] cert_db a path to the certificates database
 *
 * @return an error code of zero if there is no error
 */
PN_EXTERN int pn_messenger_set_trusted_certificates(pn_messenger_t *messenger, const char *cert_db);

/**
 * Gets the trusted certificates database for a messenger.
 *
 * @param[in] messenger a messenger object
 * @return path to the trusted certificates database
 */
PN_EXTERN const char *pn_messenger_get_trusted_certificates(pn_messenger_t *messenger);

/**
 * Set the default timeout for a messenger.
 *
 * Any messenger call that blocks during execution will stop blocking
 * and return control when this timeout is reached, if you have set it
 * to a value greater than zero. The timeout is expressed in
 * milliseconds.
 *
 * @param[in] messenger a messenger object
 * @param[in] timeout a new timeout for the messenger, in milliseconds
 * @return an error code or zero if there is no error
 */
PN_EXTERN int pn_messenger_set_timeout(pn_messenger_t *messenger, int timeout);

/**
 * Gets the timeout for a messenger object.
 *
 * See ::pn_messenger_set_timeout() for details.
 *
 * @param[in] messenger a messenger object
 * @return the timeout for the messenger, in milliseconds
 */
PN_EXTERN int pn_messenger_get_timeout(pn_messenger_t *messenger);

/**
 * Check if a messenger is in blocking mode.
 *
 * @param[in] messenger a messenger object
 * @return true if blocking has been enabled, false otherwise
 */
PN_EXTERN bool pn_messenger_is_blocking(pn_messenger_t *messenger);

/**
 * Enable or disable blocking behavior for a messenger during calls to
 * ::pn_messenger_send and ::pn_messenger_recv.
 *
 * @param[in] messenger a messenger object
 * @param[in] blocking the value of the blocking flag
 * @return an error code or zero if there is no error
 */
PN_EXTERN int pn_messenger_set_blocking(pn_messenger_t *messenger, bool blocking);

/**
 * Check if a messenger is in passive mode.
 *
 * A messenger that is in passive mode will never attempt to perform
 * I/O internally, but instead will make all internal file descriptors
 * accessible through ::pn_messenger_selectable() to be serviced
 * externally. This can be useful for integrating messenger into an
 * external event loop.
 *
 * @param[in] messenger a messenger object
 * @return true if the messenger is in passive mode, false otherwise
 */
PN_EXTERN bool pn_messenger_is_passive(pn_messenger_t *messenger);

/**
 * Set the passive mode for a messenger.
 *
 * See ::pn_messenger_is_passive() for details on passive mode.
 *
 * @param[in] messenger a messenger object
 * @param[in] passive true to enable passive mode, false to disable
 * passive mode
 * @return an error code or zero on success
 */
PN_EXTERN int pn_messenger_set_passive(pn_messenger_t *messenger, bool passive);

/** Frees a Messenger.
 *
 * @param[in] messenger the messenger to free (or NULL), no longer
 *                      valid on return
 */
PN_EXTERN void pn_messenger_free(pn_messenger_t *messenger);

/**
 * Get the code for a messenger's most recent error.
 *
 * The error code is initialized to zero at messenger creation. The
 * error number is "sticky" i.e. error codes are not reset to 0 at the
 * end of successful API calls. You can use ::pn_messenger_error to
 * access the messenger's error object and clear explicitly if
 * desired.
 *
 * @param[in] messenger the messenger to check for errors
 * @return an error code or zero if there is no error
 * @see error.h
 */
PN_EXTERN int pn_messenger_errno(pn_messenger_t *messenger);

/**
 * Get a messenger's error object.
 *
 * Returns a pointer to a pn_error_t that is valid until the messenger
 * is freed. The pn_error_* API allows you to access the text, error
 * number, and lets you set or clear the error code explicitly.
 *
 * @param[in] messenger the messenger to check for errors
 * @return a pointer to the messenger's error descriptor
 * @see error.h
 */
PN_EXTERN pn_error_t *pn_messenger_error(pn_messenger_t *messenger);

/**
 * Get the size of a messenger's outgoing window.
 *
 * The size of the outgoing window limits the number of messages whose
 * status you can check with a tracker. A message enters this window
 * when you call pn_messenger_put on the message. For example, if your
 * outgoing window size is 10, and you call pn_messenger_put 12 times,
 * new status information will no longer be available for the first 2
 * messages.
 *
 * The default outgoing window size is 0.
 *
 * @param[in] messenger a messenger object
 * @return the outgoing window for the messenger
 */
PN_EXTERN int pn_messenger_get_outgoing_window(pn_messenger_t *messenger);

/**
 * Set the size of a messenger's outgoing window.
 *
 * See ::pn_messenger_get_outgoing_window() for details.
 *
 * @param[in] messenger a messenger object
 * @param[in] window the number of deliveries to track
 * @return an error or zero on success
 * @see error.h
 */
PN_EXTERN int pn_messenger_set_outgoing_window(pn_messenger_t *messenger, int window);

/**
 * Get the size of a messenger's incoming window.
 *
 * The size of a messenger's incoming window limits the number of
 * messages that can be accepted or rejected using trackers. Messages
 * *do not* enter this window when they have been received
 * (::pn_messenger_recv) onto you incoming queue. Messages only enter
 * this window only when you access them using pn_messenger_get. If
 * your incoming window size is N, and you get N+1 messages without
 * explicitly accepting or rejecting the oldest message, then it will
 * be implicitly accepted when it falls off the edge of the incoming
 * window.
 *
 * The default incoming window size is 0.
 *
 * @param[in] messenger a messenger object
 * @return the incoming window for the messenger
 */
PN_EXTERN int pn_messenger_get_incoming_window(pn_messenger_t *messenger);

/**
 * Set the size of a messenger's incoming window.
 *
 * See ::pn_messenger_get_incoming_window() for details.
 *
 * @param[in] messenger a messenger object
 * @param[in] window the number of deliveries to track
 * @return an error or zero on success
 * @see error.h
 */
PN_EXTERN int pn_messenger_set_incoming_window(pn_messenger_t *messenger,
                                               int window);

/**
 * Currently a no-op placeholder. For future compatibility, do not
 * send or receive messages before starting the messenger.
 *
 * @param[in] messenger the messenger to start
 * @return an error code or zero on success
 * @see error.h
 */
PN_EXTERN int pn_messenger_start(pn_messenger_t *messenger);

/**
 * Stops a messenger.
 *
 * Stopping a messenger will perform an orderly shutdown of all
 * underlying connections. This may require some time. If the
 * messenger is in non blocking mode (see ::pn_messenger_is_blocking),
 * this operation will return PN_INPROGRESS if it cannot finish
 * immediately. In that case, you can use ::pn_messenger_stopped() to
 * determine when the messenger has finished stopping.
 *
 * @param[in] messenger the messenger to stop
 * @return an error code or zero on success
 * @see error.h
 */
PN_EXTERN int pn_messenger_stop(pn_messenger_t *messenger);

/**
 * Returns true if a messenger is in the stopped state. This function
 * does not block.
 *
 * @param[in] messenger the messenger to stop
 *
 */
PN_EXTERN bool pn_messenger_stopped(pn_messenger_t *messenger);

/**
 * Subscribes a messenger to messages from the specified source.
 *
 * @param[in] messenger the messenger to subscribe
 * @param[in] source
 * @return a subscription
 */
PN_EXTERN pn_subscription_t *pn_messenger_subscribe(pn_messenger_t *messenger, const char *source);

/**
 * Subscribes a messenger to messages from the specified source with the given
 * timeout for the subscription's lifetime.
 *
 * @param[in] messenger the messenger to subscribe
 * @param[in] source
 * @param[in] timeout the maximum time to keep the subscription alive once the
 *            link is closed.
 * @return a subscription
 */
PN_EXTERN pn_subscription_t *
pn_messenger_subscribe_ttl(pn_messenger_t *messenger, const char *source,
                           pn_seconds_t timeout);

/**
 * Get a link based on link name and whether the link is a sender or receiver
 *
 * @param[in] messenger the messenger to get the link from
 * @param[in] address the link address that identifies the link to receive
 * @param[in] sender true if the link is a sender, false if the link is a
 *            receiver
 * @return a link, or NULL if no link matches the address / sender parameters
 */
PN_EXTERN pn_link_t *pn_messenger_get_link(pn_messenger_t *messenger,
                                           const char *address, bool sender);

/**
 * Get a subscription's application context.
 *
 * See ::pn_subscription_set_context().
 *
 * @param[in] sub a subscription object
 * @return the subscription's application context
 */
PN_EXTERN void *pn_subscription_get_context(pn_subscription_t *sub);

/**
 * Set an application context for a subscription.
 *
 * @param[in] sub a subscription object
 * @param[in] context the application context for the subscription
 */
PN_EXTERN void pn_subscription_set_context(pn_subscription_t *sub, void *context);

/**
 * Get the source address of a subscription.
 *
 * @param[in] sub a subscription object
 * @return the subscription's source address
 */
PN_EXTERN const char *pn_subscription_address(pn_subscription_t *sub);

/**
 * Puts a message onto the messenger's outgoing queue. The message may
 * also be sent if transmission would not cause blocking. This call
 * will not block.
 *
 * @param[in] messenger a messenger object
 * @param[in] msg a message to put on the messenger's outgoing queue
 * @return an error code or zero on success
 * @see error.h
 */
PN_EXTERN int pn_messenger_put(pn_messenger_t *messenger, pn_message_t *msg);

/**
 * Track the status of a delivery.
 *
 * Get the current status of the delivery associated with the supplied
 * tracker. This may return PN_STATUS_UNKOWN if the tracker has fallen
 * outside the incoming/outgoing tracking windows of the messenger.
 *
 * @param[in] messenger the messenger
 * @param[in] tracker the tracker identifying the delivery
 * @return a status code for the delivery
 */
PN_EXTERN pn_status_t pn_messenger_status(pn_messenger_t *messenger, pn_tracker_t tracker);

/**
 * Get delivery information about a delivery.
 *
 * Returns the delivery information associated with the supplied tracker.
 * This may return NULL if the tracker has fallen outside the
 * incoming/outgoing tracking windows of the messenger.
 *
 * @param[in] messenger the messenger
 * @param[in] tracker the tracker identifying the delivery
 * @return a pn_delivery_t representing the delivery.
 */
PN_EXTERN pn_delivery_t *pn_messenger_delivery(pn_messenger_t *messenger,
                                               pn_tracker_t tracker);

/**
 * Check if the delivery associated with a given tracker is still
 * waiting to be sent.
 *
 * Note that returning false does not imply that the delivery was
 * actually sent over the wire.
 *
 * @param[in] messenger the messenger
 * @param[in] tracker the tracker identifying the delivery
 *
 * @return true if the delivery is still buffered
 */
PN_EXTERN bool pn_messenger_buffered(pn_messenger_t *messenger, pn_tracker_t tracker);

/**
 * Frees a Messenger from tracking the status associated with a given
 * tracker. Use the PN_CUMULATIVE flag to indicate everything up to
 * (and including) the given tracker.
 *
 * @param[in] messenger the Messenger
 * @param[in] tracker identifies a delivery
 * @param[in] flags 0 or PN_CUMULATIVE
 *
 * @return an error code or zero on success
 * @see error.h
 */
PN_EXTERN int pn_messenger_settle(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);

/**
 * Get a tracker for the outgoing message most recently given to
 * pn_messenger_put.
 *
 * This tracker may be used with pn_messenger_status to determine the
 * delivery status of the message, as long as the message is still
 * within your outgoing window.
 *
 * @param[in] messenger the messenger
 *
 * @return a pn_tracker_t or an undefined value if pn_messenger_get
 *         has never been called for the given messenger
 */
PN_EXTERN pn_tracker_t pn_messenger_outgoing_tracker(pn_messenger_t *messenger);

/**
 * Sends or receives any outstanding messages queued for a messenger.
 * This will block for the indicated timeout.
 *
 * @param[in] messenger the Messenger
 * @param[in] timeout the maximum time to block in milliseconds, -1 ==
 * forever, 0 == do not block
 *
 * @return 0 if no work to do, < 0 if error, or 1 if work was done.
 */
PN_EXTERN int pn_messenger_work(pn_messenger_t *messenger, int timeout);

/**
 * Interrupt a messenger object that may be blocking in another
 * thread.
 *
 * The messenger interface is single-threaded. This is the only
 * messenger function intended to be concurrently called from another
 * thread. It will interrupt any messenger function which is currently
 * blocking and cause it to return with a status of ::PN_INTR.
 *
 * @param[in] messenger the Messenger to interrupt
 */
PN_EXTERN int pn_messenger_interrupt(pn_messenger_t *messenger);

/**
 * Send messages from a messenger's outgoing queue.
 *
 * If a messenger is in blocking mode (see
 * ::pn_messenger_is_blocking()), this operation will block until N
 * messages have been sent from the outgoing queue. A value of -1 for
 * N means "all messages in the outgoing queue". See below for a full
 * definition of what sent from the outgoing queue means.
 *
 * Any blocking will end once the messenger's configured timeout (if
 * any) has been reached. When this happens an error code of
 * ::PN_TIMEOUT is returned.
 *
 * If the messenger is in non blocking mode, this call will return an
 * error code of ::PN_INPROGRESS if it is unable to send the requested
 * number of messages without blocking.
 *
 * A message is considered to be sent from the outgoing queue when its
 * status has been fully determined. This does not necessarily mean
 * the message was successfully sent to the final recipient though,
 * for example of the receiver rejects the message, the final status
 * will be ::PN_STATUS_REJECTED. Similarly, if a message is sent to an
 * invalid address, it may be removed from the outgoing queue without
 * ever even being transmitted. In this case the final status will be
 * ::PN_STATUS_ABORTED.
 *
 * @param[in] messenger a messenger object
 * @param[in] n the number of messages to send
 *
 * @return an error code or zero on success
 * @see error.h
 */
PN_EXTERN int pn_messenger_send(pn_messenger_t *messenger, int n);

/**
 * Retrieve messages into a messenger's incoming queue.
 *
 * Instructs a messenger to receive up to @c limit messages into the
 * incoming message queue of a messenger. If @c limit is -1, the
 * messenger will receive as many messages as it can buffer
 * internally. If the messenger is in blocking mode, this call will
 * block until at least one message is available in the incoming
 * queue.
 *
 * Each call to pn_messenger_recv replaces the previous receive
 * operation, so pn_messenger_recv(messenger, 0) will cancel any
 * outstanding receive.
 *
 * After receiving messages onto your incoming queue use
 * ::pn_messenger_get() to access message content.
 *
 * @param[in] messenger the messenger
 * @param[in] limit the maximum number of messages to receive or -1 to
 *                  to receive as many messages as it can buffer
 *                  internally.
 * @return an error code or zero on success
 * @see error.h
 */
PN_EXTERN int pn_messenger_recv(pn_messenger_t *messenger, int limit);

/**
 * Get the capacity of the incoming message queue of a messenger.
 *
 * Note this count does not include those messages already available
 * on the incoming queue (@see pn_messenger_incoming()). Rather it
 * returns the number of incoming queue entries available for
 * receiving messages.
 *
 * @param[in] messenger the messenger
 */
PN_EXTERN int pn_messenger_receiving(pn_messenger_t *messenger);

/**
 * Get the next message from the head of a messenger's incoming queue.
 *
 * The get operation copies the message data from the head of the
 * messenger's incoming queue into the provided ::pn_message_t object.
 * If provided ::pn_message_t pointer is NULL, the head essage will be
 * discarded. This operation will return ::PN_EOS if there are no
 * messages left on the incoming queue.
 *
 * @param[in] messenger a messenger object
 * @param[out] message upon return contains the message from the head of the queue
 * @return an error code or zero on success
 * @see error.h
 */
PN_EXTERN int pn_messenger_get(pn_messenger_t *messenger, pn_message_t *message);

/**
 * Get a tracker for the message most recently retrieved by
 * ::pn_messenger_get().
 *
 * A tracker for an incoming message allows you to accept or reject
 * the associated message. It can also be used for cumulative
 * accept/reject operations for the associated message and all prior
 * messages as well.
 *
 * @param[in] messenger a messenger object
 * @return a pn_tracker_t or an undefined value if pn_messenger_get
 *         has never been called for the given messenger
 */
PN_EXTERN pn_tracker_t pn_messenger_incoming_tracker(pn_messenger_t *messenger);

/**
 * Get the subscription of the message most recently retrieved by ::pn_messenger_get().
 *
 * This operation will return NULL if ::pn_messenger_get() has never
 * been succesfully called.
 *
 * @param[in] messenger a messenger object
 * @return a pn_subscription_t or NULL
 */
PN_EXTERN pn_subscription_t *pn_messenger_incoming_subscription(pn_messenger_t *messenger);

/**
 * Indicates that an accept or reject should operate cumulatively.
 */
#define PN_CUMULATIVE (0x1)

/**
 * Signal successful processing of message(s).
 *
 * With no flags this operation will signal the sender that the
 * message referenced by the tracker was accepted. If the
 * PN_CUMULATIVE flag is set, this operation will also reject all
 * pending messages prior to the message indicated by the tracker.
 *
 * Note that when a message is accepted or rejected multiple times,
 * either explicitly, or implicitly through use of the ::PN_CUMULATIVE
 * flag, only the first outcome applies. For example if a sequence of
 * three messages are received: M1, M2, M3, and M2 is rejected, and M3
 * is cumulatively accepted, M2 will remain rejected and only M1 and
 * M3 will be considered accepted.
 *
 * @param[in] messenger a messenger object
 * @param[in] tracker an incoming tracker
 * @param[in] flags 0 or PN_CUMULATIVE
 * @return an error code or zero on success
 * @see error.h
 */
PN_EXTERN int pn_messenger_accept(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);

/**
 * Signal unsuccessful processing of message(s).
 *
 * With no flags this operation will signal the sender that the
 * message indicated by the tracker was rejected. If the PN_CUMULATIVE
 * flag is used this operation will also reject all pending messages
 * prior to the message indicated by the tracker.
 *
 * Note that when a message is accepted or rejected multiple times,
 * either explicitly, or implicitly through use of the ::PN_CUMULATIVE
 * flag, only the first outcome applies. For example if a sequence of
 * three messages are received: M1, M2, M3, and M2 is accepted, and M3
 * is cumulatively rejected, M2 will remain accepted and only M1 and
 * M3 will be considered rejected.
 *
 * @param[in] messenger a messenger object
 * @param[in] tracker an incoming tracker
 * @param[in] flags 0 or PN_CUMULATIVE
 * @return an error code or zero on success
 * @see error.h
 */
PN_EXTERN int pn_messenger_reject(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);

/**
 * Get  link for the message referenced by the given tracker.
 *
 * @param[in] messenger a messenger object
 * @param[in] tracker a tracker object
 * @return a pn_link_t or NULL if the link could not be determined.
 */
PN_EXTERN pn_link_t *pn_messenger_tracker_link(pn_messenger_t *messenger,
                                               pn_tracker_t tracker);

/**
 * Get the number of messages in the outgoing message queue of a
 * messenger.
 *
 * @param[in] messenger a messenger object
 * @return the outgoing queue depth
 */
PN_EXTERN int pn_messenger_outgoing(pn_messenger_t *messenger);

/**
 * Get the number of messages in the incoming message queue of a messenger.
 *
 * @param[in] messenger a messenger object
 * @return the incoming queue depth
 */
PN_EXTERN int pn_messenger_incoming(pn_messenger_t *messenger);

//! Adds a routing rule to a Messenger's internal routing table.
//!
//! The route procedure may be used to influence how a messenger will
//! internally treat a given address or class of addresses. Every call
//! to the route procedure will result in messenger appending a routing
//! rule to its internal routing table.
//!
//! Whenever a message is presented to a messenger for delivery, it
//! will match the address of this message against the set of routing
//! rules in order. The first rule to match will be triggered, and
//! instead of routing based on the address presented in the message,
//! the messenger will route based on the address supplied in the rule.
//!
//! The pattern matching syntax supports two types of matches, a '%'
//! will match any character except a '/', and a '*' will match any
//! character including a '/'.
//!
//! A routing address is specified as a normal AMQP address, however it
//! may additionally use substitution variables from the pattern match
//! that triggered the rule.
//!
//! Any message sent to "foo" will be routed to "amqp://foo.com":
//!
//!   pn_messenger_route("foo", "amqp://foo.com");
//!
//! Any message sent to "foobar" will be routed to
//! "amqp://foo.com/bar":
//!
//!   pn_messenger_route("foobar", "amqp://foo.com/bar");
//!
//! Any message sent to bar/&lt;path&gt; will be routed to the corresponding
//! path within the amqp://bar.com domain:
//!
//!   pn_messenger_route("bar/*", "amqp://bar.com/$1");
//!
//! Route all messages over TLS:
//!
//!   pn_messenger_route("amqp:*", "amqps:$1")
//!
//! Supply credentials for foo.com:
//!
//!   pn_messenger_route("amqp://foo.com/*", "amqp://user:password@foo.com/$1");
//!
//! Supply credentials for all domains:
//!
//!   pn_messenger_route("amqp://*", "amqp://user:password@$1");
//!
//! Route all addresses through a single proxy while preserving the
//! original destination:
//!
//!   pn_messenger_route("amqp://%/*", "amqp://user:password@proxy/$1/$2");
//!
//! Route any address through a single broker:
//!
//!   pn_messenger_route("*", "amqp://user:password@broker/$1");
//!
//! @param[in] messenger the Messenger
//! @param[in] pattern a glob pattern
//! @param[in] address an address indicating alternative routing
//!
//! @return an error code or zero on success
//! @see error.h
PN_EXTERN int pn_messenger_route(pn_messenger_t *messenger, const char *pattern,
                                 const char *address);

/**
 * Rewrite message addresses prior to transmission.
 *
 * This operation is similar to pn_messenger_route, except that the
 * destination of the message is determined before the message address
 * is rewritten.
 *
 * The outgoing address is only rewritten after routing has been
 * finalized.  If a message has an outgoing address of
 * "amqp://0.0.0.0:5678", and a rewriting rule that changes its
 * outgoing address to "foo", it will still arrive at the peer that
 * is listening on "amqp://0.0.0.0:5678", but when it arrives there,
 * the receiver will see its outgoing address as "foo".
 *
 * The default rewrite rule removes username and password from
 * addresses before they are transmitted.
 *
 * @param[in] messenger a messenger object
 * @param[in] pattern a glob pattern to select messages
 * @param[in] address an address indicating outgoing address rewrite
 * @return an error code or zero on success
 */
PN_EXTERN int pn_messenger_rewrite(pn_messenger_t *messenger, const char *pattern,
                                   const char *address);

/**
 * Extract @link pn_selectable_t selectables @endlink from a passive
 * messenger.
 *
 * A messenger that is in passive mode (see
 * ::pn_messenger_is_passive()) will never attempt to perform any I/O
 * internally, but instead make its internal file descriptors
 * available for external processing via the
 * ::pn_messenger_selectable() operation.
 *
 * An application wishing to perform I/O on behalf of a passive
 * messenger must extract all available selectables by calling this
 * operation until it returns NULL. The ::pn_selectable_t interface
 * may then be used by the application to perform I/O outside the
 * messenger.
 *
 * All selectables returned by this operation must be serviced until
 * they reach a terminal state and then freed. See
 * ::pn_selectable_is_terminal() for more details.
 *
 * By default any given selectable will only ever be returned once by
 * this operation, however if the selectable's registered flag is set
 * to true (see ::pn_selectable_set_registered()), then the selectable
 * will be returned whenever its interest set may have changed.
 *
 * @param[in] messenger a messenger object
 * @return the next selectable, or NULL if there are none left
 */
PN_EXTERN pn_selectable_t *pn_messenger_selectable(pn_messenger_t *messenger);

/**
 * Get the nearest deadline for selectables associated with a messenger.
 *
 * @param[in] messenger a messenger object
 * @return the nearest deadline
 */
PN_EXTERN pn_timestamp_t pn_messenger_deadline(pn_messenger_t *messenger);

/**
 * @}
 */

#define PN_FLAGS_CHECK_ROUTES                                                  \
  (0x1) /** Messenger flag to indicate that a call                             \
            to pn_messenger_start should check that                            \
            any defined routes are valid */

#define PN_FLAGS_ALLOW_INSECURE_MECHS                                          \
  (0x2) /** Messenger flag to indicate that the PLAIN                          \
            mechanism is allowed on an unencrypted                             \
            connection */

/** Sets control flags to enable additional function for the Messenger.
 *
 * @param[in] messenger the messenger
 * @param[in] flags 0 or PN_FLAGS_CHECK_ROUTES
 *
 * @return an error code of zero if there is no error
 */
PN_EXTERN int pn_messenger_set_flags(pn_messenger_t *messenger,
                                     const int flags);

/** Gets the flags for a Messenger.
 *
 * @param[in] messenger the messenger
 * @return The flags set for the messenger
 */
PN_EXTERN int pn_messenger_get_flags(pn_messenger_t *messenger);

/**
 * Set the local sender settle mode for the underlying link.
 *
 * @param[in] messenger the messenger
 * @param[in] mode the sender settle mode
 */
PN_EXTERN int pn_messenger_set_snd_settle_mode(pn_messenger_t *messenger,
                                               const pn_snd_settle_mode_t mode);

/**
 * Set the local receiver settle mode for the underlying link.
 *
 * @param[in] messenger the messenger
 * @param[in] mode the receiver settle mode
 */
PN_EXTERN int pn_messenger_set_rcv_settle_mode(pn_messenger_t *messenger,
                                               const pn_rcv_settle_mode_t mode);

/**
 * Set the tracer associated with a messenger.
 *
 * @param[in] messenger a messenger object
 * @param[in] tracer the tracer callback
 */
PN_EXTERN void pn_messenger_set_tracer(pn_messenger_t *messenger,
                                       pn_tracer_t tracer);

/**
 * Gets the remote idle timeout for the specified remote service address
 *
 * @param[in] messenger a messenger object
 * @param[in] address of remote service whose idle timeout is required
 * @return the timeout in milliseconds or -1 if an error occurs
 */
PN_EXTERN pn_millis_t
    pn_messenger_get_remote_idle_timeout(pn_messenger_t *messenger,
                                         const char *address);

/**
 * Sets the SSL peer authentiacation mode required when a trust
 * certificate is used.
 *
 * @param[in] messenger a messenger object
 * @param[in] mode the mode required (see pn_ssl_verify_mode_t
 *             enum for valid values)
 * @return 0 if successful or -1 if an error occurs
 */
PN_EXTERN int
pn_messenger_set_ssl_peer_authentication_mode(pn_messenger_t *messenger,
                                              const pn_ssl_verify_mode_t mode);

#ifdef __cplusplus
}
#endif

#endif /* messenger.h */