0
# AMQP Types and Constants
1

2
Type system for AMQP values and comprehensive constants for protocol states, error codes, and configuration options that provide the foundation for AMQP 1.0 protocol operations.
3

4
## Capabilities
5

6
### AMQP Type System
7

8
Base classes and specific types for representing AMQP 1.0 protocol values with proper encoding and decoding.
9

10
#### Base AMQP Type
11

12
```python { .api }
13
class AMQPType:
14
    def __init__(self, value):
15
        """
16
        Base class for AMQP types.
17

18
        Parameters:
19
        - value: The Python value to wrap
20
        """
21

22
    @property
23
    def value: any
24
        """The Python value."""
25

26
    @property 
27
    def c_data: any
28
        """The underlying C data structure."""
29
```
30

31
#### Specific AMQP Types
32

33
```python { .api }
34
class AMQPSymbol(AMQPType):
35
    """AMQP symbol type for identifiers and names."""
36

37
class AMQPChar(AMQPType):
38
    """Single UTF-32 character type."""
39

40
class AMQPLong(AMQPType):
41
    """64-bit signed integer type."""
42

43
class AMQPuLong(AMQPType):
44
    """64-bit unsigned integer type."""
45

46
class AMQPInt(AMQPType):
47
    """32-bit signed integer type."""
48

49
class AMQPuInt(AMQPType):
50
    """32-bit unsigned integer type."""
51

52
class AMQPShort(AMQPType):
53
    """16-bit signed integer type."""
54

55
class AMQPuShort(AMQPType):
56
    """16-bit unsigned integer type."""
57

58
class AMQPByte(AMQPType):
59
    """8-bit signed integer type."""
60

61
class AMQPuByte(AMQPType):
62
    """8-bit unsigned integer type."""
63

64
class AMQPArray(AMQPType):
65
    """Array of AMQP values of the same type."""
66

67
class AMQPDescribed(AMQPType):
68
    """Described value with descriptor and actual value."""
69
```
70

71
**Usage Examples:**
72

73
```python
74
from uamqp.types import AMQPSymbol, AMQPLong, AMQPArray
75

76
# Symbol type for identifiers
77
symbol = AMQPSymbol("queue-name")
78

79
# Numeric types
80
long_val = AMQPLong(9223372036854775807)
81
uint_val = AMQPuInt(4294967295)
82

83
# Array type
84
numbers = AMQPArray([1, 2, 3, 4, 5])
85

86
# Use in message properties
87
from uamqp import Message
88
from uamqp.message import MessageProperties
89

90
properties = MessageProperties(
91
    message_id=AMQPSymbol("msg-12345"),
92
    group_sequence=AMQPuInt(1)
93
)
94
message = Message("data", properties=properties)
95
```
96

97
## Protocol Constants
98

99
### Message States
100

101
States that indicate the processing status of messages during send/receive operations.
102

103
```python { .api }
104
class MessageState:
105
    WaitingToBeSent = 0      # Message queued for sending
106
    WaitingForSendAck = 1    # Message sent, waiting for acknowledgment
107
    SendComplete = 2         # Message successfully sent and acknowledged
108
    SendFailed = 3           # Message send failed
109
    ReceivedUnsettled = 4    # Message received but not settled
110
    ReceivedSettled = 5      # Message received and settled
111
```
112

113
### Send Results
114

115
Results returned from message send operations.
116

117
```python { .api }
118
class MessageSendResult:
119
    Ok = 0          # Send operation succeeded
120
    Error = 1       # Send operation failed with error
121
    Timeout = 2     # Send operation timed out
122
    Cancelled = 3   # Send operation was cancelled
123
```
124

125
### Link States
126

127
States for AMQP links (message senders and receivers).
128

129
```python { .api }
130
class MessageSenderState:
131
    Idle = 0       # Sender not active
132
    Opening = 1    # Sender opening
133
    Open = 2       # Sender ready for messages
134
    Closing = 3    # Sender closing
135
    Error = 4      # Sender in error state
136

137
class MessageReceiverState:
138
    Idle = 0       # Receiver not active
139
    Opening = 1    # Receiver opening
140
    Open = 2       # Receiver ready for messages
141
    Closing = 3    # Receiver closing
142
    Error = 4      # Receiver in error state
143
```
144

145
### Transport Types
146

147
Available transport protocols for AMQP connections.
148

149
```python { .api }
150
class TransportType:
151
    Amqp = 0                # Standard AMQP over TCP
152
    AmqpOverWebsocket = 1   # AMQP over WebSocket
153
```
154

155
**Usage Example:**
156

157
```python
158
from uamqp.constants import TransportType
159
from uamqp.authentication import SASLPlain
160

161
# Use WebSocket transport for firewall-friendly connections
162
auth = SASLPlain(
163
    hostname="amqp.example.com",
164
    username="user",
165
    password="pass", 
166
    transport_type=TransportType.AmqpOverWebsocket,
167
    port=443
168
)
169
```
170

171
### Message Body Types
172

173
Types of message body content supported by AMQP 1.0.
174

175
```python { .api }
176
class MessageBodyType:
177
    Data = 0        # Binary data sections
178
    Value = 1       # Single AMQP value
179
    Sequence = 2    # Sequence of AMQP values
180
```
181

182
**Usage Example:**
183

184
```python
185
from uamqp import Message
186
from uamqp.constants import MessageBodyType
187

188
# Explicit body type specification
189
message = Message(
190
    body={"key": "value"}, 
191
    body_type=MessageBodyType.Value
192
)
193
```
194

195
### Settlement Modes
196

197
Configuration for message acknowledgment behavior.
198

199
```python { .api }
200
class SenderSettleMode:
201
    Unsettled = 0  # Sender waits for receiver disposition
202
    Settled = 1    # Sender considers message settled immediately
203
    Mixed = 2      # Sender may use either mode per message
204

205
class ReceiverSettleMode:
206
    PeekLock = 0        # First: receive, second: settle (explicit ack)
207
    ReceiveAndDelete = 1 # Auto-settle on receive
208
```
209

210
**Usage Example:**
211

212
```python
213
from uamqp import SendClient, ReceiveClient
214
from uamqp.constants import SenderSettleMode, ReceiverSettleMode
215

216
# Fire-and-forget sending
217
send_client = SendClient(
218
    target,
219
    auth=auth,
220
    send_settle_mode=SenderSettleMode.Settled
221
)
222

223
# Manual acknowledgment receiving
224
receive_client = ReceiveClient(
225
    source,
226
    auth=auth,
227
    receive_settle_mode=ReceiverSettleMode.PeekLock
228
)
229
```
230

231
### Link Roles
232

233
Roles that links can take in AMQP connections.
234

235
```python { .api }
236
class Role:
237
    Sender = 0    # Link sends messages
238
    Receiver = 1  # Link receives messages
239
```
240

241
### Error Codes
242

243
Standard AMQP error condition codes.
244

245
```python { .api }
246
class ErrorCodes:
247
    InternalServerError = "amqp:internal-error"
248
    NotFound = "amqp:not-found"
249
    UnauthorizedAccess = "amqp:unauthorized-access"
250
    DecodeError = "amqp:decode-error"
251
    ResourceLimitExceeded = "amqp:resource-limit-exceeded"
252
    NotAllowed = "amqp:not-allowed"
253
    InvalidField = "amqp:invalid-field"
254
    NotImplemented = "amqp:not-implemented"
255
    ResourceLocked = "amqp:resource-locked"
256
    PreconditionFailed = "amqp:precondition-failed"
257
    ResourceDeleted = "amqp:resource-deleted"
258
    IllegalState = "amqp:illegal-state"
259
    FrameSizeTooSmall = "amqp:frame-size-too-small"
260
```
261

262
### Authentication States
263

264
States for CBS (Claims-Based Security) authentication operations.
265

266
```python { .api }
267
class CBSOperationResult:
268
    Ok = 0              # Authentication succeeded
269
    Error = 1           # Authentication failed
270
    OperationFailed = 2 # Operation failed
271
    Timeout = 3         # Authentication timed out
272

273
class CBSOpenState:
274
    Closed = 0    # CBS link closed
275
    Opening = 1   # CBS link opening
276
    Open = 2      # CBS link open and ready
277
    Error = 3     # CBS link in error state
278

279
class CBSAuthStatus:
280
    Idle = 0           # Not authenticating
281
    InProgress = 1     # Authentication in progress
282
    Complete = 2       # Authentication complete
283
    Expired = 3        # Authentication expired
284
    Error = 4          # Authentication error
285
    RefreshRequired = 5 # Token refresh required
286
```
287

288
### Management Operation States
289

290
States for AMQP management operations.
291

292
```python { .api }
293
class MgmtExecuteResult:
294
    Ok = 0          # Management operation succeeded
295
    Error = 1       # Management operation failed
296
    Timeout = 2     # Management operation timed out
297

298
class MgmtOpenStatus:
299
    Closed = 0   # Management link closed
300
    Opening = 1  # Management link opening
301
    Open = 2     # Management link open
302
    Error = 3    # Management link in error state
303
```
304

305
## Numeric Constants
306

307
### Default Ports
308

309
```python { .api }
310
DEFAULT_AMQPS_PORT = 5671        # Default AMQPS (TLS) port
311
DEFAULT_AMQP_WSS_PORT = 443      # Default AMQP WebSocket Secure port
312
```
313

314
### Authentication Timing
315

316
```python { .api }
317
AUTH_EXPIRATION_SECS = 3600      # Default token expiration (1 hour)
318
AUTH_REFRESH_SECS = 600          # Default token refresh interval (10 minutes)
319
```
320

321
### Size Limits
322

323
```python { .api }
324
MAX_FRAME_SIZE_BYTES = 65536      # Maximum AMQP frame size (64KB)
325
MAX_MESSAGE_LENGTH_BYTES = 1048576 # Maximum message length (1MB)
326
```
327

328
### Message Format
329

330
```python { .api }
331
BATCH_MESSAGE_FORMAT = 0x80013700  # Batch message format identifier
332
```
333

334
**Usage Examples:**
335

336
```python
337
from uamqp.constants import (
338
    DEFAULT_AMQPS_PORT, 
339
    MAX_FRAME_SIZE_BYTES,
340
    AUTH_EXPIRATION_SECS
341
)
342

343
# Use default port
344
auth = SASLPlain("amqp.example.com", "user", "pass", port=DEFAULT_AMQPS_PORT)
345

346
# Configure frame size
347
client = SendClient(target, auth=auth, max_frame_size=MAX_FRAME_SIZE_BYTES)
348

349
# Token expiration
350
import datetime
351
expires_at = datetime.datetime.utcnow() + datetime.timedelta(seconds=AUTH_EXPIRATION_SECS)
352
```
353

354
## Common Usage Patterns
355

356
### Type Conversion
357

358
```python
359
from uamqp.types import AMQPSymbol, AMQPLong
360

361
# Convert Python values to AMQP types
362
message_id = AMQPSymbol("msg-12345")  # String to symbol
363
sequence_num = AMQPLong(1001)         # Int to long
364

365
# Use in message properties
366
properties = {"message-id": message_id, "sequence": sequence_num}
367
```
368

369
### State Checking
370

371
```python
372
from uamqp.constants import MessageState, MessageSenderState
373

374
# Check message send results
375
results = client.send_all_messages()
376
for result in results:
377
    if result == MessageState.SendComplete:
378
        print("Message sent successfully")
379
    elif result == MessageState.SendFailed:
380
        print("Message send failed")
381

382
# Check sender state
383
if sender.get_state() == MessageSenderState.Open:
384
    # Sender is ready for messages
385
    sender.send_async(message)
386
```
387

388
### Configuration with Constants
389

390
```python
391
from uamqp.constants import (
392
    TransportType, 
393
    SenderSettleMode, 
394
    ReceiverSettleMode
395
)
396

397
# WebSocket transport with specific settlement modes
398
send_client = SendClient(
399
    target,
400
    auth=auth,
401
    transport_type=TransportType.AmqpOverWebsocket,
402
    send_settle_mode=SenderSettleMode.Mixed
403
)
404

405
receive_client = ReceiveClient(
406
    source,
407
    auth=auth,
408
    receive_settle_mode=ReceiverSettleMode.PeekLock
409
)
410
```