WebSphere Message Brokers
File: ac11010_
Writer: Kate Hostler

Reference topic

This build: July 31, 2007 21:18:11

SUBSCRIBE Subscribe to named topics

The SUBSCRIBE message allows a client to register an interest in one or more topic names with the broker. Messages published to these topics are delivered from the broker to the client as PUBLISH messages. The SUBSCRIBE message also specifies the QoS level at which the subscriber wants to receive published messages.

Fixed header

The table below shows the fixed header format.

bit 7 6 5 4 3 2 1 0
byte 1 Message Type (8) DUP flag QoS level RETAIN
  1 0 0 0 0 0 1 x
byte 2 Remaining Length
QoS level
SUBSCRIBE messages use QoS level 1 to acknowledge multiple subscription requests. The corresponding SUBACK message is identified by matching the Message ID. This also handles SUBSCRIBE messages retries in the same way as PUBLISH messages.
DUP flag
In this example the DUP flag is set to zero (0) to indicate that the message is being sent for the first time. If this message is being re-sent because a SUBACK message has not arrived after a specified timeout period, the DUP bit is set to indicate to the broker that it might be a duplicate of a message already received.
RETAIN flag
Not used.
Remaining Length field
The length of the payload. It can be a multibyte field.

Variable header

The variable header contains a Message ID because a SUBSCRIBE message has a QoS level of 1.

Typically, the protocol library generates the Message ID, and passes it back to the publishing application, for example as a return handle. This prevents multiple applications, or multiple publishing threads, running on a single client from generating duplicate Message IDs.

Message ID 0 (0x0000) is reserved as an invalid Message ID, and must not be used. The Message ID is a 16-bit unsigned integer, which typically increases by exactly one from one message to the next, but is not required to do so. The two bytes of the Message ID are ordered as MSB, followed by LSB (big-endian).

The table below shows an example format for the variable header with a Message ID of 10.

  Description 7 6 5 4 3 2 1 0
Message Identifier
byte 1 Message ID MSB (0) 0 0 0 0 0 0 0 0
byte 2 Message ID LSB (10) 0 0 0 0 1 0 1 0

Payload

The payload of a SUBSCRIBE message contains a list of topic names to which the client wants to subscribe, and the QoS level at which the client wants to receive the messages. The strings are UTF-encoded, and the QoS level occupies 2 bits of a single byte. These topic/QoS pairs are packed contiguously as shown in the example payload in the table below.

Topic name "a/b"
Requested QoS 1
Topic name "c/d"
Requested QoS 2

Topic names in a SUBSCRIBE message are not compressed.

The format of the example payload is shown in the table below.

  Description 7 6 5 4 3 2 1 0
Topic name
byte 1 Length MSB (0) 0 0 0 0 0 0 0 0
byte 2 Length LSB (3) 0 0 0 0 0 0 1 1
byte 3 'a' (0x61) 0 1 1 0 0 0 0 1
byte 4 '/' (0x2F) 0 0 1 0 1 1 1 1
byte 5 'b' (0x62) 0 1 1 0 0 0 1 0
Requested QoS
byte 6 Requested QoS (1) x x x x x x 0 1
Topic Name
byte 7 Length MSB (0) 0 0 0 0 0 0 0 0
byte 8 Length LSB (3) 0 0 0 0 0 0 1 1
byte 9 'c' (0x63) 0 1 1 0 0 0 1 1
byte 10 '/' (0x2F) 0 0 1 0 1 1 1 1
byte 11 'd' (0x64) 0 1 1 0 0 1 0 0
Requested QoS
byte 12 Requested QoS (2) x x x x x x 1 0

Assuming that the requested QoS level is granted, the client receives PUBLISH messages at less than or equal to this level, depending on the QoS level of the original message from the publisher. For example, if a client has a QoS level 1 subscription to a particular topic, then a QoS level 0 PUBLISH message to that topic is delivered to the client at QoS level 0. A QoS level 2 PUBLISH message to the same topic is downgraded to QoS level 1 for delivery to the client.

A corollary to this is that subscribing to a topic at QoS level 2 is equivalent to saying "I would like to receive messages on this topic at the QoS at which they are published".

The Requested QoS field is encoded in the byte following each UTF-encoded topic name as shown in the table below.

bit 7 6 5 4 3 2 1 0
  Reserved Reserved Reserved Reserved Reserved Reserved QoS level
  x x x x x x    

The upper 6 bits of this byte are not used in the current version of the protocol. They are reserved for future use.

Response

When it receives a SUBSCRIBE message from a client, the broker responds with a SUBACK message.

Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:18:11

ac11010_ This topic's URL is: