axl_bool myqtt_conn_sub ( MyQttConn conn,
int  wait_sub,
const char *  topic_filter,
MyQttQos  qos,
int *  subs_result 
)

Allows to subscribe to one topic.

Parameters
connThe connection where the operation will take place.
topic_filterTopic filter to subscribe to.
wait_subHow long to wait for subscription operation to complete. Value provided must be in microseconds: 10 seconds -> 10000000 If 0 is provided, no wait operation will be implemented. If -1 is provided, a default wait of 10 seconds will be implemented (10000000).
qosRequested QoS, maximum QoS level at which the server can send publications to this client. Note that this is a request that must be granted by the server. Use subs_result param to get an indication about the QoS that was finally granted.
subs_resultReference to a integer value where the function will report subscription result. If subs_result is NULL, no subscription result will be reported. In the case subs_result is provided, it can either -1 (indicating that subscription was rejected/denied by the server or there was any other error) or any value of MyQttQos.
Returns
The function reports axl_true in the case the subscription request was completed without any error. In the case of a connection failure, subscription failure or timeout, the function will report axl_false. The function also reports axl_false in the case conn and any topic_filter provided is NULL.

About QoS to use for subscriptions:

From OASIS Standard definition: "The requested QoS gives the maximum QoS level at which the Server can send publications to the Client (3.4.3 Payload section).

When you subscribe with a certain QoS to the broker you are telling the server to send you all publish operations using that provided QoS level. This has the direct implication that all guaranties (or none) will be applied according to the QoS you select.

If a you receive a message that was published using QoS 2 but you subscribed using QoS 1, then the message QoS will be downgraded to QoS 1 (for this particular subscription).

  • Use MYQTT_QOS_0 in the case you don't care about missing some messages you can use MYQTT_QOS_0 which means that any message published to the subscribed topic will be sent to you with QoS 0 (even though it was published with QoS 1 o 2).
  • Use MYQTT_QOS_1 in the case you want message retention while you are disconnected (don't forget to setup clean_session to axl_false when connecting) you can use MYQTT_QOS_1. This will make the broker to send you messages published with QoS 1, ensuring that the message reaches your client at least once (but be aware you can receive duplicates, see myqtt_msg_get_dup_flag).
  • Use MYQTT_QOS_2 in the case you want all guaranties provided by MQTT protocol and you want to receive all messages and only one time. This is the highest level provided by MQTT which ensures all messages are delivered. This is recommended for critical applications where no message can be lost. However, it is the QoS that causes more overhead because it needs to store and confirm every message on every step. Note that if you set a QoS of 2, it doesn't imply that a published message with QoS 0 will be upgraded to QoS 2.

As you can see these is a different process when selecting the QOS when publishing (myqtt_conn_pub). That is, when sending publications to the broker there is a configurable QoS and when receiving those publications there is also another QoS configuration.

No upgrade of QoS happens (as opposed to downgrade described):

Keep in mind that an upgrade of QoS never happens (as opposed to the downgrade when subscribing with a QoS that is lower than message's QoS).

This means that subscribing with QoS 2 ensures that you receive QoS 2 published message as is, but for those messages having QoS 1 and QoS 0 will be received as is too (no upgrade happens from 0 to 2 or from 1 to 2).

That's why the standard says: Subscribing to a Topic Filter at QoS 2 is equivalent to saying "I would like to receive Messages matching this filter at the QoS with which they were published". This means a publisher is responsible for determining the maximum QoS a Message can be delivered at, but a subscriber is able to require that the Server downgrades the QoS to one more suitable for its usage.

References msg, myqtt_conn_is_ok(), myqtt_msg_get_type_str(), myqtt_msg_unref(), MYQTT_SUBACK, and MYQTT_SUBSCRIBE.