0
# High-Level Messaging API
1

2
Simple functions for common messaging operations that provide the easiest way to send and receive AMQP messages without managing connections or sessions directly.
3

4
## Capabilities
5

6
### Send Single Message
7

8
Sends a single message to an AMQP endpoint with automatic connection management and cleanup.
9

10
```python { .api }
11
def send_message(target, data, auth=None, debug=False):
12
    """
13
    Send a single message to AMQP endpoint.
14

15
    Parameters:
16
    - target (str, bytes, or Target): The target AMQP endpoint
17
    - data (str, bytes, or Message): The contents of the message to send
18
    - auth (AMQPAuth, optional): Authentication credentials (defaults to SASLAnonymous)
19
    - debug (bool): Whether to turn on network trace logs
20

21
    Returns:
22
    list[MessageState]: A list of states for each message sent
23
    """
24
```
25

26
**Usage Example:**
27

28
```python
29
import uamqp
30
from uamqp.authentication import SASLPlain
31

32
# Send simple string message
33
target = "amqps://servicebus.example.com/myqueue"
34
auth = SASLPlain("myuser", "mypassword")
35
result = uamqp.send_message(target, "Hello World", auth=auth)
36

37
# Send custom message object
38
from uamqp import Message
39
message = Message("Hello World", properties={'message_id': '123'})
40
result = uamqp.send_message(target, message, auth=auth)
41
```
42

43
### Receive Single Message
44

45
Receives a single message from an AMQP endpoint with automatic connection management.
46

47
```python { .api }
48
def receive_message(source, auth=None, timeout=0, debug=False):
49
    """
50
    Receive a single message from an AMQP endpoint.
51

52
    Parameters:
53
    - source (str, bytes, or Source): The AMQP source endpoint to receive from
54
    - auth (AMQPAuth, optional): Authentication credentials (defaults to SASLAnonymous)
55
    - timeout (int): Timeout in milliseconds (0 = no timeout)
56
    - debug (bool): Whether to turn on network trace logs
57

58
    Returns:
59
    Message or None: The received message, or None if timeout reached
60
    """
61
```
62

63
**Usage Example:**
64

65
```python
66
import uamqp
67
from uamqp.authentication import SASLPlain
68

69
source = "amqps://servicebus.example.com/myqueue"
70
auth = SASLPlain("myuser", "mypassword")
71

72
# Receive with 30 second timeout
73
message = uamqp.receive_message(source, auth=auth, timeout=30000)
74
if message:
75
    print(f"Received: {message.get_data()}")
76
    message.accept()  # Acknowledge the message
77
else:
78
    print("No message received within timeout")
79
```
80

81
### Receive Multiple Messages
82

83
Receives a batch of messages from an AMQP endpoint with configurable batch size and timeout.
84

85
```python { .api }
86
def receive_messages(source, auth=None, max_batch_size=None, timeout=0, debug=False, **kwargs):
87
    """
88
    Receive a batch of messages from an AMQP endpoint.
89

90
    Parameters:
91
    - source (str, bytes, or Source): The AMQP source endpoint to receive from
92
    - auth (AMQPAuth, optional): Authentication credentials (defaults to SASLAnonymous)
93
    - max_batch_size (int, optional): Maximum number of messages to return
94
    - timeout (int): Timeout in milliseconds (0 = no timeout)
95
    - debug (bool): Whether to turn on network trace logs
96
    - **kwargs: Additional receiver configuration options
97

98
    Returns:
99
    list[Message]: List of received messages (may be empty if timeout reached)
100
    """
101

102
def get_platform_info():
103
    """
104
    Get current platform and library information.
105

106
    Returns:
107
    str: Platform information string including library version and platform details
108
    """
109
```
110

111
**Usage Example:**
112

113
```python
114
import uamqp
115
from uamqp.authentication import SASTokenAuth
116

117
source = "amqps://servicebus.example.com/myqueue"
118
token = "SharedAccessSignature sr=..."
119
auth = SASTokenAuth("servicebus.example.com", token=token)
120

121
# Receive up to 10 messages with 5 second timeout
122
messages = uamqp.receive_messages(
123
    source, 
124
    auth=auth, 
125
    max_batch_size=10, 
126
    timeout=5000
127
)
128

129
print(f"Received {len(messages)} messages")
130
for message in messages:
131
    print(f"Message: {message.get_data()}")
132
    message.accept()  # Acknowledge each message
133
```
134

135
### Get Platform Information
136

137
Retrieves platform and library version information useful for debugging and diagnostics.
138

139
**Usage Example:**
140

141
```python
142
import uamqp
143

144
# Get platform information
145
platform_info = uamqp.get_platform_info()
146
print(f"Platform info: {platform_info}")
147

148
# Typical output might include library version, platform, and build info
149
```
150

151
## Error Handling
152

153
All high-level messaging functions may raise AMQP-related exceptions:
154

155
- **AMQPConnectionError**: Connection to broker failed
156
- **AMQPError**: General AMQP protocol error
157
- **AuthenticationException**: Authentication failed
158
- **MessageSendFailed**: Message sending failed
159
- **ClientTimeout**: Operation timed out
160

161
```python
162
import uamqp
163
from uamqp.errors import AMQPConnectionError, AuthenticationException
164

165
try:
166
    message = uamqp.receive_message(source, auth=auth, timeout=10000)
167
    if message:
168
        message.accept()
169
except AMQPConnectionError as e:
170
    print(f"Connection failed: {e}")
171
except AuthenticationException as e:
172
    print(f"Authentication failed: {e}")
173
```
174

175
## Common Parameters
176

177
### Authentication Types
178

179
All high-level messaging functions accept these authentication types:
180

181
- **None**: Uses SASLAnonymous (for brokers that allow anonymous access)
182
- **SASLPlain**: Username/password authentication
183
- **SASLAnonymous**: Anonymous authentication (explicit)
184
- **SASTokenAuth**: Shared Access Signature token authentication
185
- **JWTTokenAuth**: JSON Web Token authentication
186

187
### Target and Source Formats
188

189
Target and source parameters accept:
190

191
- **String**: AMQP URI (e.g., "amqps://host:5671/queue")
192
- **Bytes**: AMQP URI as bytes
193
- **Target/Source objects**: For advanced configuration with filters, properties, etc.
194

195
### Debug Mode
196

197
Setting `debug=True` enables network trace logging at INFO level, useful for troubleshooting connection and protocol issues.