diff --git a/MQTTAsync.h b/MQTTAsync.h deleted file mode 100644 index e11af04..0000000 --- a/MQTTAsync.h +++ /dev/null @@ -1,2383 +0,0 @@ -/******************************************************************************* - * Copyright (c) 2009, 2023 IBM Corp., Ian Craggs and others - * - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v2.0 - * and Eclipse Distribution License v1.0 which accompany this distribution. - * - * The Eclipse Public License is available at - * https://www.eclipse.org/legal/epl-2.0/ - * and the Eclipse Distribution License is available at - * http://www.eclipse.org/org/documents/edl-v10.php. - * - * Contributors: - * Ian Craggs - initial API and implementation - * Ian Craggs, Allan Stockdill-Mander - SSL connections - * Ian Craggs - multiple server connection support - * Ian Craggs - MQTT 3.1.1 support - * Ian Craggs - fix for bug 444103 - success/failure callbacks not invoked - * Ian Craggs - automatic reconnect and offline buffering (send while disconnected) - * Ian Craggs - binary will message - * Ian Craggs - binary password - * Ian Craggs - remove const on eyecatchers #168 - * Ian Craggs - MQTT 5.0 - *******************************************************************************/ - -/********************************************************************/ - -/** - * @cond MQTTAsync_main - * @mainpage Asynchronous MQTT client library for C (MQTTAsync) - * - * © Copyright 2009, 2023 IBM Corp., Ian Craggs and others - * - * @brief An Asynchronous MQTT client library for C. - * - * An MQTT client application connects to MQTT-capable servers. - * A typical client is responsible for collecting information from a telemetry - * device and publishing the information to the server. It can also subscribe - * to topics, receive messages, and use this information to control the - * telemetry device. - * - * MQTT clients implement the published MQTT v3 protocol. You can write your own - * API to the MQTT protocol using the programming language and platform of your - * choice. This can be time-consuming and error-prone. - * - * To simplify writing MQTT client applications, this library encapsulates - * the MQTT v3 protocol for you. Using this library enables a fully functional - * MQTT client application to be written in a few lines of code. - * The information presented here documents the API provided - * by the Asynchronous MQTT Client library for C. - * - * Using the client
- * Applications that use the client library typically use a similar structure: - * - * Some simple examples are shown here: - * - * Additional information about important concepts is provided here: - * - * @endcond - */ - -/* -/// @cond EXCLUDE -*/ -#if !defined(MQTTASYNC_H) -#define MQTTASYNC_H - -#if defined(__cplusplus) - extern "C" { -#endif - -#include -/* -/// @endcond -*/ - -#include "MQTTExportDeclarations.h" - -#include "MQTTProperties.h" -#include "MQTTReasonCodes.h" -#include "MQTTSubscribeOpts.h" -#if !defined(NO_PERSISTENCE) -#include "MQTTClientPersistence.h" -#endif - -/** - * Return code: No error. Indicates successful completion of an MQTT client - * operation. - */ -#define MQTTASYNC_SUCCESS 0 -/** - * Return code: A generic error code indicating the failure of an MQTT client - * operation. - */ -#define MQTTASYNC_FAILURE -1 - -/* error code -2 is MQTTAsync_PERSISTENCE_ERROR */ - -#define MQTTASYNC_PERSISTENCE_ERROR -2 - -/** - * Return code: The client is disconnected. - */ -#define MQTTASYNC_DISCONNECTED -3 -/** - * Return code: The maximum number of messages allowed to be simultaneously - * in-flight has been reached. - */ -#define MQTTASYNC_MAX_MESSAGES_INFLIGHT -4 -/** - * Return code: An invalid UTF-8 string has been detected. - */ -#define MQTTASYNC_BAD_UTF8_STRING -5 -/** - * Return code: A NULL parameter has been supplied when this is invalid. - */ -#define MQTTASYNC_NULL_PARAMETER -6 -/** - * Return code: The topic has been truncated (the topic string includes - * embedded NULL characters). String functions will not access the full topic. - * Use the topic length value to access the full topic. - */ -#define MQTTASYNC_TOPICNAME_TRUNCATED -7 -/** - * Return code: A structure parameter does not have the correct eyecatcher - * and version number. - */ -#define MQTTASYNC_BAD_STRUCTURE -8 -/** - * Return code: A qos parameter is not 0, 1 or 2 - */ -#define MQTTASYNC_BAD_QOS -9 -/** - * Return code: All 65535 MQTT msgids are being used - */ -#define MQTTASYNC_NO_MORE_MSGIDS -10 -/** - * Return code: the request is being discarded when not complete - */ -#define MQTTASYNC_OPERATION_INCOMPLETE -11 -/** - * Return code: no more messages can be buffered - */ -#define MQTTASYNC_MAX_BUFFERED_MESSAGES -12 -/** - * Return code: Attempting SSL connection using non-SSL version of library - */ -#define MQTTASYNC_SSL_NOT_SUPPORTED -13 -/** - * Return code: protocol prefix in serverURI should be: - * @li @em tcp:// or @em mqtt:// - Insecure TCP - * @li @em ssl:// or @em mqtts:// - Encrypted SSL/TLS - * @li @em ws:// - Insecure websockets - * @li @em wss:// - Secure web sockets - * - * The TLS enabled prefixes (ssl, mqtts, wss) are only valid if the TLS - * version of the library is linked with. - */ -#define MQTTASYNC_BAD_PROTOCOL -14 -/** - * Return code: don't use options for another version of MQTT - */ -#define MQTTASYNC_BAD_MQTT_OPTION -15 -/** - * Return code: call not applicable to the client's version of MQTT - */ -#define MQTTASYNC_WRONG_MQTT_VERSION -16 -/** - * Return code: 0 length will topic - */ -#define MQTTASYNC_0_LEN_WILL_TOPIC -17 -/* - * Return code: connect or disconnect command ignored because there is already a connect or disconnect - * command at the head of the list waiting to be processed. Use the onSuccess/onFailure callbacks to wait - * for the previous connect or disconnect command to be complete. - */ -#define MQTTASYNC_COMMAND_IGNORED -18 - /* - * Return code: maxBufferedMessages in the connect options must be >= 0 - */ - #define MQTTASYNC_MAX_BUFFERED -19 - -/** - * Default MQTT version to connect with. Use 3.1.1 then fall back to 3.1 - */ -#define MQTTVERSION_DEFAULT 0 -/** - * MQTT version to connect with: 3.1 - */ -#define MQTTVERSION_3_1 3 -/** - * MQTT version to connect with: 3.1.1 - */ -#define MQTTVERSION_3_1_1 4 -/** - * MQTT version to connect with: 5 - */ -#define MQTTVERSION_5 5 -/** - * Bad return code from subscribe, as defined in the 3.1.1 specification - */ -#define MQTT_BAD_SUBSCRIBE 0x80 - - -/** - * Initialization options - */ -typedef struct -{ - /** The eyecatcher for this structure. Must be MQTG. */ - char struct_id[4]; - /** The version number of this structure. Must be 0 */ - int struct_version; - /** 1 = we do openssl init, 0 = leave it to the application */ - int do_openssl_init; -} MQTTAsync_init_options; - -#define MQTTAsync_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 } - -/** - * Global init of mqtt library. Call once on program start to set global behaviour. - * handle_openssl_init - if mqtt library should handle openssl init (1) or rely on the caller to init it before using mqtt (0) - */ -LIBMQTT_API void MQTTAsync_global_init(MQTTAsync_init_options* inits); - -/** - * A handle representing an MQTT client. A valid client handle is available - * following a successful call to MQTTAsync_create(). - */ -typedef void* MQTTAsync; -/** - * A value representing an MQTT message. A token is returned to the - * client application when a message is published. The token can then be used to - * check that the message was successfully delivered to its destination (see - * MQTTAsync_publish(), - * MQTTAsync_publishMessage(), - * MQTTAsync_deliveryComplete(), and - * MQTTAsync_getPendingTokens()). - */ -typedef int MQTTAsync_token; - -/** - * A structure representing the payload and attributes of an MQTT message. The - * message topic is not part of this structure (see MQTTAsync_publishMessage(), - * MQTTAsync_publish(), MQTTAsync_receive(), MQTTAsync_freeMessage() - * and MQTTAsync_messageArrived()). - */ -typedef struct -{ - /** The eyecatcher for this structure. must be MQTM. */ - char struct_id[4]; - /** The version number of this structure. Must be 0 or 1. - * 0 indicates no message properties */ - int struct_version; - /** The length of the MQTT message payload in bytes. */ - int payloadlen; - /** A pointer to the payload of the MQTT message. */ - void* payload; - /** - * The quality of service (QoS) assigned to the message. - * There are three levels of QoS: - *
- *
QoS0
- *
Fire and forget - the message may not be delivered
- *
QoS1
- *
At least once - the message will be delivered, but may be - * delivered more than once in some circumstances.
- *
QoS2
- *
Once and one only - the message will be delivered exactly once.
- *
- */ - int qos; - /** - * The retained flag serves two purposes depending on whether the message - * it is associated with is being published or received. - * - * retained = true
- * For messages being published, a true setting indicates that the MQTT - * server should retain a copy of the message. The message will then be - * transmitted to new subscribers to a topic that matches the message topic. - * For subscribers registering a new subscription, the flag being true - * indicates that the received message is not a new one, but one that has - * been retained by the MQTT server. - * - * retained = false
- * For publishers, this indicates that this message should not be retained - * by the MQTT server. For subscribers, a false setting indicates this is - * a normal message, received as a result of it being published to the - * server. - */ - int retained; - /** - * The dup flag indicates whether or not this message is a duplicate. - * It is only meaningful when receiving QoS1 messages. When true, the - * client application should take appropriate action to deal with the - * duplicate message. This is an output parameter only. - */ - int dup; - /** The message identifier is reserved for internal use by the - * MQTT client and server. It is an output parameter only - writing - * to it will serve no purpose. It contains the MQTT message id of - * an incoming publish message. - */ - int msgid; - /** - * The MQTT V5 properties associated with the message. - */ - MQTTProperties properties; -} MQTTAsync_message; - -#define MQTTAsync_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer } - -/** - * This is a callback function. The client application - * must provide an implementation of this function to enable asynchronous - * receipt of messages. The function is registered with the client library by - * passing it as an argument to MQTTAsync_setCallbacks(). It is - * called by the client library when a new message that matches a client - * subscription has been received from the server. This function is executed on - * a separate thread to the one on which the client application is running. - * - * Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be - * called within this callback. - * @param context A pointer to the context value originally passed to - * MQTTAsync_setCallbacks(), which contains any application-specific context. - * @param topicName The topic associated with the received message. - * @param topicLen The length of the topic if there are one - * more NULL characters embedded in topicName, otherwise topicLen - * is 0. If topicLen is 0, the value returned by strlen(topicName) - * can be trusted. If topicLen is greater than 0, the full topic name - * can be retrieved by accessing topicName as a byte array of length - * topicLen. - * @param message The MQTTAsync_message structure for the received message. - * This structure contains the message payload and attributes. - * @return This function must return 0 or 1 indicating whether or not - * the message has been safely received by the client application.
- * Returning 1 indicates that the message has been successfully handled. - * To free the message storage, ::MQTTAsync_freeMessage must be called. - * To free the topic name storage, ::MQTTAsync_free must be called.
- * Returning 0 indicates that there was a problem. In this - * case, the client library will reinvoke MQTTAsync_messageArrived() to - * attempt to deliver the message to the application again. - * Do not free the message and topic storage when returning 0, otherwise - * the redelivery will fail. - */ -typedef int MQTTAsync_messageArrived(void* context, char* topicName, int topicLen, MQTTAsync_message* message); - -/** - * This is a callback function. The client application - * must provide an implementation of this function to enable asynchronous - * notification of delivery of messages to the server. The function is - * registered with the client library by passing it as an argument to MQTTAsync_setCallbacks(). - * It is called by the client library after the client application has - * published a message to the server. It indicates that the necessary - * handshaking and acknowledgements for the requested quality of service (see - * MQTTAsync_message.qos) have been completed. This function is executed on a - * separate thread to the one on which the client application is running. - * - * Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be - * called within this callback. - * @param context A pointer to the context value originally passed to - * MQTTAsync_setCallbacks(), which contains any application-specific context. - * @param token The ::MQTTAsync_token associated with - * the published message. Applications can check that all messages have been - * correctly published by matching the tokens returned from calls to - * MQTTAsync_send() and MQTTAsync_sendMessage() with the tokens passed - * to this callback. - */ -typedef void MQTTAsync_deliveryComplete(void* context, MQTTAsync_token token); - -/** - * This is a callback function. The client application - * must provide an implementation of this function to enable asynchronous - * notification of the loss of connection to the server. The function is - * registered with the client library by passing it as an argument to - * MQTTAsync_setCallbacks(). It is called by the client library if the client - * loses its connection to the server. The client application must take - * appropriate action, such as trying to reconnect or reporting the problem. - * This function is executed on a separate thread to the one on which the - * client application is running. - * - * Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be - * called within this callback. - * @param context A pointer to the context value originally passed to - * MQTTAsync_setCallbacks(), which contains any application-specific context. - * @param cause The reason for the disconnection. - * Currently, cause is always set to NULL. - */ -typedef void MQTTAsync_connectionLost(void* context, char* cause); - - -/** - * This is a callback function, which will be called when the client - * library successfully connects. This is superfluous when the connection - * is made in response to a MQTTAsync_connect call, because the onSuccess - * callback can be used. It is intended for use when automatic reconnect - * is enabled, so that when a reconnection attempt succeeds in the background, - * the application is notified and can take any required actions. - * - * Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be - * called within this callback. - * @param context A pointer to the context value originally passed to - * MQTTAsync_setCallbacks(), which contains any application-specific context. - * @param cause The reason for the disconnection. - * Currently, cause is always set to NULL. - */ -typedef void MQTTAsync_connected(void* context, char* cause); - -/** - * This is a callback function, which will be called when the client - * library receives a disconnect packet from the server. This applies to MQTT V5 and above only. - * - * Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be - * called within this callback. - * @param context A pointer to the context value originally passed to - * MQTTAsync_setCallbacks(), which contains any application-specific context. - * @param properties the properties in the disconnect packet. - * @param properties the reason code from the disconnect packet - * Currently, cause is always set to NULL. - */ -typedef void MQTTAsync_disconnected(void* context, MQTTProperties* properties, - enum MQTTReasonCodes reasonCode); - -/** - * Sets the MQTTAsync_disconnected() callback function for a client. - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * - * Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be - * called within this callback. - * @param context A pointer to any application-specific context. The - * the context pointer is passed to each of the callback functions to - * provide access to the context information in the callback. - * @param co A pointer to an MQTTAsync_connected() callback - * function. NULL removes the callback setting. - * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set, - * ::MQTTASYNC_FAILURE if an error occurred. - */ -LIBMQTT_API int MQTTAsync_setDisconnected(MQTTAsync handle, void* context, MQTTAsync_disconnected* co); - -/** The connect options that can be updated before an automatic reconnect. */ -typedef struct -{ - /** The eyecatcher for this structure. Will be MQCD. */ - char struct_id[4]; - /** The version number of this structure. Will be 0 */ - int struct_version; - /** - * MQTT servers that support the MQTT v3.1 protocol provide authentication - * and authorisation by user name and password. This is the user name parameter. - * Set data to NULL to remove. To change, allocate new - * storage with ::MQTTAsync_allocate - this will then be free later by the library. - */ - const char* username; - /** - * The password parameter of the MQTT authentication. - * Set data to NULL to remove. To change, allocate new - * storage with ::MQTTAsync_allocate - this will then be free later by the library. - */ - struct { - int len; /**< binary password length */ - const void* data; /**< binary password data */ - } binarypwd; -} MQTTAsync_connectData; - -#define MQTTAsync_connectData_initializer {{'M', 'Q', 'C', 'D'}, 0, NULL, {0, NULL}} - -/** - * This is a callback function which will allow the client application to update the - * connection data. - * @param data The connection data which can be modified by the application. - * @return Return a non-zero value to update the connect data, zero to keep the same data. - */ -typedef int MQTTAsync_updateConnectOptions(void* context, MQTTAsync_connectData* data); - -/** - * Sets the MQTTAsync_updateConnectOptions() callback function for a client. - * @param handle A valid client handle from a successful call to MQTTAsync_create(). - * @param context A pointer to any application-specific context. The - * the context pointer is passed to each of the callback functions to - * provide access to the context information in the callback. - * @param co A pointer to an MQTTAsync_updateConnectOptions() callback - * function. NULL removes the callback setting. - */ -LIBMQTT_API int MQTTAsync_setUpdateConnectOptions(MQTTAsync handle, void* context, MQTTAsync_updateConnectOptions* co); - -/** - * Sets the MQTTPersistence_beforeWrite() callback function for a client. - * @param handle A valid client handle from a successful call to MQTTAsync_create(). - * @param context A pointer to any application-specific context. The - * the context pointer is passed to the callback function to - * provide access to the context information in the callback. - * @param co A pointer to an MQTTPersistence_beforeWrite() callback - * function. NULL removes the callback setting. - */ -LIBMQTT_API int MQTTAsync_setBeforePersistenceWrite(MQTTAsync handle, void* context, MQTTPersistence_beforeWrite* co); - - -/** - * Sets the MQTTPersistence_afterRead() callback function for a client. - * @param handle A valid client handle from a successful call to MQTTAsync_create(). - * @param context A pointer to any application-specific context. The - * the context pointer is passed to the callback function to - * provide access to the context information in the callback. - * @param co A pointer to an MQTTPersistence_beforeWrite() callback - * function. NULL removes the callback setting. - */ -LIBMQTT_API int MQTTAsync_setAfterPersistenceRead(MQTTAsync handle, void* context, MQTTPersistence_afterRead* co); - - -/** The data returned on completion of an unsuccessful API call in the response callback onFailure. */ -typedef struct -{ - /** A token identifying the failed request. */ - MQTTAsync_token token; - /** A numeric code identifying the error. */ - int code; - /** Optional text explaining the error. Can be NULL. */ - const char *message; -} MQTTAsync_failureData; - - -/** The data returned on completion of an unsuccessful API call in the response callback onFailure. */ -typedef struct -{ - /** The eyecatcher for this structure. Will be MQFD. */ - char struct_id[4]; - /** The version number of this structure. Will be 0 */ - int struct_version; - /** A token identifying the failed request. */ - MQTTAsync_token token; - /** The MQTT reason code returned. */ - enum MQTTReasonCodes reasonCode; - /** The MQTT properties on the ack, if any. */ - MQTTProperties properties; - /** A numeric code identifying the MQTT client library error. */ - int code; - /** Optional further text explaining the error. Can be NULL. */ - const char *message; - /** Packet type on which the failure occurred - used for publish QoS 1/2 exchanges*/ - int packet_type; -} MQTTAsync_failureData5; - -#define MQTTAsync_failureData5_initializer {{'M', 'Q', 'F', 'D'}, 0, 0, MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, 0, NULL, 0} - -/** The data returned on completion of a successful API call in the response callback onSuccess. */ -typedef struct -{ - /** A token identifying the successful request. Can be used to refer to the request later. */ - MQTTAsync_token token; - /** A union of the different values that can be returned for subscribe, unsubscribe and publish. */ - union - { - /** For subscribe, the granted QoS of the subscription returned by the server. - * Also for subscribeMany, if only 1 subscription was requested. */ - int qos; - /** For subscribeMany, if more than one subscription was requested, - * the list of granted QoSs of the subscriptions returned by the server. */ - int* qosList; - /** For publish, the message being sent to the server. */ - struct - { - MQTTAsync_message message; /**< the message being sent to the server */ - char* destinationName; /**< the topic destination for the message */ - } pub; - /* For connect, the server connected to, MQTT version used, and sessionPresent flag */ - struct - { - char* serverURI; /**< the connection string of the server */ - int MQTTVersion; /**< the version of MQTT being used */ - int sessionPresent; /**< the session present flag returned from the server */ - } connect; - } alt; -} MQTTAsync_successData; - - -/** The data returned on completion of a successful API call in the response callback onSuccess. */ -typedef struct -{ - char struct_id[4]; /**< The eyecatcher for this structure. Will be MQSD. */ - int struct_version; /**< The version number of this structure. Will be 0 */ - /** A token identifying the successful request. Can be used to refer to the request later. */ - MQTTAsync_token token; - enum MQTTReasonCodes reasonCode; /**< MQTT V5 reason code returned */ - MQTTProperties properties; /**< MQTT V5 properties returned, if any */ - /** A union of the different values that can be returned for subscribe, unsubscribe and publish. */ - union - { - /** For subscribeMany, the list of reasonCodes returned by the server. */ - struct - { - int reasonCodeCount; /**< the number of reason codes in the reasonCodes array */ - enum MQTTReasonCodes* reasonCodes; /**< an array of reasonCodes */ - } sub; - /** For publish, the message being sent to the server. */ - struct - { - MQTTAsync_message message; /**< the message being sent to the server */ - char* destinationName; /**< the topic destination for the message */ - } pub; - /* For connect, the server connected to, MQTT version used, and sessionPresent flag */ - struct - { - char* serverURI; /**< the connection string of the server */ - int MQTTVersion; /**< the version of MQTT being used */ - int sessionPresent; /**< the session present flag returned from the server */ - } connect; - /** For unsubscribeMany, the list of reasonCodes returned by the server. */ - struct - { - int reasonCodeCount; /**< the number of reason codes in the reasonCodes array */ - enum MQTTReasonCodes* reasonCodes; /**< an array of reasonCodes */ - } unsub; - } alt; -} MQTTAsync_successData5; - -#define MQTTAsync_successData5_initializer {{'M', 'Q', 'S', 'D'}, 0, 0, MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, {.sub={0,0}}} - -/** - * This is a callback function. The client application - * must provide an implementation of this function to enable asynchronous - * notification of the successful completion of an API call. The function is - * registered with the client library by passing it as an argument in - * ::MQTTAsync_responseOptions. - * - * Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be - * called within this callback. - * @param context A pointer to the context value originally passed to - * ::MQTTAsync_responseOptions, which contains any application-specific context. - * @param response Any success data associated with the API completion. - */ -typedef void MQTTAsync_onSuccess(void* context, MQTTAsync_successData* response); - -/** - * This is a callback function, the MQTT V5 version of ::MQTTAsync_onSuccess. - * The client application - * must provide an implementation of this function to enable asynchronous - * notification of the successful completion of an API call. The function is - * registered with the client library by passing it as an argument in - * ::MQTTAsync_responseOptions. - * - * Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be - * called within this callback. - * @param context A pointer to the context value originally passed to - * ::MQTTAsync_responseOptions, which contains any application-specific context. - * @param response Any success data associated with the API completion. - */ -typedef void MQTTAsync_onSuccess5(void* context, MQTTAsync_successData5* response); - -/** - * This is a callback function. The client application - * must provide an implementation of this function to enable asynchronous - * notification of the unsuccessful completion of an API call. The function is - * registered with the client library by passing it as an argument in - * ::MQTTAsync_responseOptions. - * - * Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be - * called within this callback. - * @param context A pointer to the context value originally passed to - * ::MQTTAsync_responseOptions, which contains any application-specific context. - * @param response Failure data associated with the API completion. - */ -typedef void MQTTAsync_onFailure(void* context, MQTTAsync_failureData* response); - -/** - * This is a callback function, the MQTT V5 version of ::MQTTAsync_onFailure. - * The application must provide an implementation of this function to enable asynchronous - * notification of the unsuccessful completion of an API call. The function is - * registered with the client library by passing it as an argument in - * ::MQTTAsync_responseOptions. - * - * Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be - * called within this callback. - * @param context A pointer to the context value originally passed to - * ::MQTTAsync_responseOptions, which contains any application-specific context. - * @param response Failure data associated with the API completion. - */ -typedef void MQTTAsync_onFailure5(void* context, MQTTAsync_failureData5* response); - -/** Structure to define call options. For MQTT 5.0 there is input data as well as that - * describing the response method. So there is now also a synonym ::MQTTAsync_callOptions - * to better reflect the use. This responseOptions name is kept for backward - * compatibility. - */ -typedef struct MQTTAsync_responseOptions -{ - /** The eyecatcher for this structure. Must be MQTR */ - char struct_id[4]; - /** The version number of this structure. Must be 0 or 1 - * if 0, no MQTTV5 options */ - int struct_version; - /** - * A pointer to a callback function to be called if the API call successfully - * completes. Can be set to NULL, in which case no indication of successful - * completion will be received. - */ - MQTTAsync_onSuccess* onSuccess; - /** - * A pointer to a callback function to be called if the API call fails. - * Can be set to NULL, in which case no indication of unsuccessful - * completion will be received. - */ - MQTTAsync_onFailure* onFailure; - /** - * A pointer to any application-specific context. The - * the context pointer is passed to success or failure callback functions to - * provide access to the context information in the callback. - */ - void* context; - /** - * A token is returned from the call. It can be used to track - * the state of this request, both in the callbacks and in future calls - * such as ::MQTTAsync_waitForCompletion. This is output only - any - * change by the application will be ignored. - */ - MQTTAsync_token token; - /** - * A pointer to a callback function to be called if the API call successfully - * completes. Can be set to NULL, in which case no indication of successful - * completion will be received. - */ - MQTTAsync_onSuccess5* onSuccess5; - /** - * A pointer to a callback function to be called if the API call successfully - * completes. Can be set to NULL, in which case no indication of successful - * completion will be received. - */ - MQTTAsync_onFailure5* onFailure5; - /** - * MQTT V5 input properties - */ - MQTTProperties properties; - /* - * MQTT V5 subscribe options, when used with subscribe only. - */ - MQTTSubscribe_options subscribeOptions; - /* - * MQTT V5 subscribe option count, when used with subscribeMany only. - * The number of entries in the subscribe_options_list array. - */ - int subscribeOptionsCount; - /* - * MQTT V5 subscribe option array, when used with subscribeMany only. - */ - MQTTSubscribe_options* subscribeOptionsList; -} MQTTAsync_responseOptions; - -#define MQTTAsync_responseOptions_initializer { {'M', 'Q', 'T', 'R'}, 1, NULL, NULL, 0, 0, NULL, NULL, MQTTProperties_initializer, MQTTSubscribe_options_initializer, 0, NULL} - -/** A synonym for responseOptions to better reflect its usage since MQTT 5.0 */ -typedef struct MQTTAsync_responseOptions MQTTAsync_callOptions; -#define MQTTAsync_callOptions_initializer MQTTAsync_responseOptions_initializer - -/** - * This function sets the global callback functions for a specific client. - * If your client application doesn't use a particular callback, set the - * relevant parameter to NULL. Any necessary message acknowledgements and - * status communications are handled in the background without any intervention - * from the client application. If you do not set a messageArrived callback - * function, you will not be notified of the receipt of any messages as a - * result of a subscription. - * - * Note: The MQTT client must be disconnected when this function is - * called. - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param context A pointer to any application-specific context. The - * the context pointer is passed to each of the callback functions to - * provide access to the context information in the callback. - * @param cl A pointer to an MQTTAsync_connectionLost() callback - * function. You can set this to NULL if your application doesn't handle - * disconnections. - * @param ma A pointer to an MQTTAsync_messageArrived() callback - * function. If this callback is not set, an error will be returned. - * You must set this callback because otherwise there would be - * no way to deliver any incoming messages. - * @param dc A pointer to an MQTTAsync_deliveryComplete() callback - * function. You can set this to NULL if you do not want to check - * for successful delivery. - * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set, - * ::MQTTASYNC_FAILURE if an error occurred. - */ -LIBMQTT_API int MQTTAsync_setCallbacks(MQTTAsync handle, void* context, MQTTAsync_connectionLost* cl, - MQTTAsync_messageArrived* ma, MQTTAsync_deliveryComplete* dc); - -/** - * This function sets the callback function for a connection lost event for - * a specific client. Any necessary message acknowledgements and status - * communications are handled in the background without any intervention - * from the client application. - * - * Note: The MQTT client must be disconnected when this function is - * called. - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param context A pointer to any application-specific context. The - * the context pointer is passed the callback functions to provide - * access to the context information in the callback. - * @param cl A pointer to an MQTTAsync_connectionLost() callback - * function. You can set this to NULL if your application doesn't handle - * disconnections. - * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set, - * ::MQTTASYNC_FAILURE if an error occurred. - */ - -LIBMQTT_API int MQTTAsync_setConnectionLostCallback(MQTTAsync handle, void* context, - MQTTAsync_connectionLost* cl); - -/** - * This function sets the callback function for a message arrived event for - * a specific client. Any necessary message acknowledgements and status - * communications are handled in the background without any intervention - * from the client application. If you do not set a messageArrived callback - * function, you will not be notified of the receipt of any messages as a - * result of a subscription. - * - * Note: The MQTT client must be disconnected when this function is - * called. - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param context A pointer to any application-specific context. The - * the context pointer is passed to the callback functions to provide - * access to the context information in the callback. - * @param ma A pointer to an MQTTAsync_messageArrived() callback - * function. You can set this to NULL if your application doesn't handle - * receipt of messages. - * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set, - * ::MQTTASYNC_FAILURE if an error occurred. - */ -LIBMQTT_API int MQTTAsync_setMessageArrivedCallback(MQTTAsync handle, void* context, - MQTTAsync_messageArrived* ma); - -/** - * This function sets the callback function for a delivery complete event - * for a specific client. Any necessary message acknowledgements and status - * communications are handled in the background without any intervention - * from the client application. - * - * Note: The MQTT client must be disconnected when this function is - * called. - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param context A pointer to any application-specific context. The - * the context pointer is passed to the callback functions to provide - * access to the context information in the callback. - * @param dc A pointer to an MQTTAsync_deliveryComplete() callback - * function. You can set this to NULL if you do not want to check - * for successful delivery. - * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set, - * ::MQTTASYNC_FAILURE if an error occurred. - */ -LIBMQTT_API int MQTTAsync_setDeliveryCompleteCallback(MQTTAsync handle, void* context, - MQTTAsync_deliveryComplete* dc); - -/** - * Sets the MQTTAsync_connected() callback function for a client. - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param context A pointer to any application-specific context. The - * the context pointer is passed to each of the callback functions to - * provide access to the context information in the callback. - * @param co A pointer to an MQTTAsync_connected() callback - * function. NULL removes the callback setting. - * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set, - * ::MQTTASYNC_FAILURE if an error occurred. - */ -LIBMQTT_API int MQTTAsync_setConnected(MQTTAsync handle, void* context, MQTTAsync_connected* co); - - -/** - * Reconnects a client with the previously used connect options. Connect - * must have previously been called for this to work. - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set, - * ::MQTTASYNC_FAILURE if an error occurred. - */ -LIBMQTT_API int MQTTAsync_reconnect(MQTTAsync handle); - - -/** - * This function creates an MQTT client ready for connection to the - * specified server and using the specified persistent storage (see - * MQTTAsync_persistence). See also MQTTAsync_destroy(). - * @param handle A pointer to an ::MQTTAsync handle. The handle is - * populated with a valid client reference following a successful return from - * this function. - * @param serverURI A null-terminated string specifying the server to - * which the client will connect. It takes the form - * protocol://host:port where protocol must be: - *
- * @em tcp:// or @em mqtt:// - Insecure TCP - *
- * @em ssl:// or @em mqtts:// - Encrypted SSL/TLS - *
- * @em ws:// - Insecure websockets - *
- * @em wss:// - Secure web sockets - *
- * The TLS enabled prefixes (ssl, mqtts, wss) are only valid if a TLS - * version of the library is linked with. - * For host, you can specify either an IP address or a host name. For - * instance, to connect to a server running on the local machines with the - * default MQTT port, specify tcp://localhost:1883. - * @param clientId The client identifier passed to the server when the - * client connects to it. It is a null-terminated UTF-8 encoded string. - * @param persistence_type The type of persistence to be used by the client: - *
- * ::MQTTCLIENT_PERSISTENCE_NONE: Use in-memory persistence. If the device or - * system on which the client is running fails or is switched off, the current - * state of any in-flight messages is lost and some messages may not be - * delivered even at QoS1 and QoS2. - *
- * ::MQTTCLIENT_PERSISTENCE_DEFAULT: Use the default (file system-based) - * persistence mechanism. Status about in-flight messages is held in persistent - * storage and provides some protection against message loss in the case of - * unexpected failure. - *
- * ::MQTTCLIENT_PERSISTENCE_USER: Use an application-specific persistence - * implementation. Using this type of persistence gives control of the - * persistence mechanism to the application. The application has to implement - * the MQTTClient_persistence interface. - * @param persistence_context If the application uses - * ::MQTTCLIENT_PERSISTENCE_NONE persistence, this argument is unused and should - * be set to NULL. For ::MQTTCLIENT_PERSISTENCE_DEFAULT persistence, it - * should be set to the location of the persistence directory (if set - * to NULL, the persistence directory used is the working directory). - * Applications that use ::MQTTCLIENT_PERSISTENCE_USER persistence set this - * argument to point to a valid MQTTClient_persistence structure. - * @return ::MQTTASYNC_SUCCESS if the client is successfully created, otherwise - * an error code is returned. - */ -LIBMQTT_API int MQTTAsync_create(MQTTAsync* handle, const char* serverURI, const char* clientId, - int persistence_type, void* persistence_context); - -/** Options for the ::MQTTAsync_createWithOptions call */ -typedef struct -{ - /** The eyecatcher for this structure. must be MQCO. */ - char struct_id[4]; - /** The version number of this structure. Must be 0, 1, 2 or 3 - * 0 means no MQTTVersion - * 1 means no allowDisconnectedSendAtAnyTime, deleteOldestMessages, restoreMessages - * 2 means no persistQoS0 - */ - int struct_version; - /** Whether to allow messages to be sent when the client library is not connected. */ - int sendWhileDisconnected; - /** The maximum number of messages allowed to be buffered. This is intended to be used to - * limit the number of messages queued while the client is not connected. It also applies - * when the client is connected, however, so has to be greater than 0. */ - int maxBufferedMessages; - /** Whether the MQTT version is 3.1, 3.1.1, or 5. To use V5, this must be set. - * MQTT V5 has to be chosen here, because during the create call the message persistence - * is initialized, and we want to know whether the format of any persisted messages - * is appropriate for the MQTT version we are going to connect with. Selecting 3.1 or - * 3.1.1 and attempting to read 5.0 persisted messages will result in an error on create. */ - int MQTTVersion; - /** - * Allow sending of messages while disconnected before a first successful connect. - */ - int allowDisconnectedSendAtAnyTime; - /* - * When the maximum number of buffered messages is reached, delete the oldest rather than the newest. - */ - int deleteOldestMessages; - /* - * Restore messages from persistence on create - or clear it. - */ - int restoreMessages; - /* - * Persist QoS0 publish commands - an option to not persist them. - */ - int persistQoS0; -} MQTTAsync_createOptions; - -#define MQTTAsync_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 2, 0, 100, MQTTVERSION_DEFAULT, 0, 0, 1, 1} - -#define MQTTAsync_createOptions_initializer5 { {'M', 'Q', 'C', 'O'}, 2, 0, 100, MQTTVERSION_5, 0, 0, 1, 1} - - -LIBMQTT_API int MQTTAsync_createWithOptions(MQTTAsync* handle, const char* serverURI, const char* clientId, - int persistence_type, void* persistence_context, MQTTAsync_createOptions* options); - -/** - * MQTTAsync_willOptions defines the MQTT "Last Will and Testament" (LWT) settings for - * the client. In the event that a client unexpectedly loses its connection to - * the server, the server publishes the LWT message to the LWT topic on - * behalf of the client. This allows other clients (subscribed to the LWT topic) - * to be made aware that the client has disconnected. To enable the LWT - * function for a specific client, a valid pointer to an MQTTAsync_willOptions - * structure is passed in the MQTTAsync_connectOptions structure used in the - * MQTTAsync_connect() call that connects the client to the server. The pointer - * to MQTTAsync_willOptions can be set to NULL if the LWT function is not - * required. - */ -typedef struct -{ - /** The eyecatcher for this structure. must be MQTW. */ - char struct_id[4]; - /** The version number of this structure. Must be 0 or 1 - 0 indicates no binary will message support - */ - int struct_version; - /** The LWT topic to which the LWT message will be published. */ - const char* topicName; - /** The LWT payload. */ - const char* message; - /** - * The retained flag for the LWT message (see MQTTAsync_message.retained). - */ - int retained; - /** - * The quality of service setting for the LWT message (see - * MQTTAsync_message.qos and @ref qos). - */ - int qos; - /** The LWT payload in binary form. This is only checked and used if the message option is NULL */ - struct - { - int len; /**< binary payload length */ - const void* data; /**< binary payload data */ - } payload; -} MQTTAsync_willOptions; - -#define MQTTAsync_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, { 0, NULL } } - -#define MQTT_SSL_VERSION_DEFAULT 0 -#define MQTT_SSL_VERSION_TLS_1_0 1 -#define MQTT_SSL_VERSION_TLS_1_1 2 -#define MQTT_SSL_VERSION_TLS_1_2 3 - -/** -* MQTTAsync_sslProperties defines the settings to establish an SSL/TLS connection using the -* OpenSSL library. It covers the following scenarios: -* - Server authentication: The client needs the digital certificate of the server. It is included -* in a store containting trusted material (also known as "trust store"). -* - Mutual authentication: Both client and server are authenticated during the SSL handshake. In -* addition to the digital certificate of the server in a trust store, the client will need its own -* digital certificate and the private key used to sign its digital certificate stored in a "key store". -* - Anonymous connection: Both client and server do not get authenticated and no credentials are needed -* to establish an SSL connection. Note that this scenario is not fully secure since it is subject to -* man-in-the-middle attacks. -*/ -typedef struct -{ - /** The eyecatcher for this structure. Must be MQTS */ - char struct_id[4]; - - /** The version number of this structure. Must be 0, 1, 2, 3, 4 or 5. - * 0 means no sslVersion - * 1 means no verify, CApath - * 2 means no ssl_error_context, ssl_error_cb - * 3 means no ssl_psk_cb, ssl_psk_context, disableDefaultTrustStore - * 4 means no protos, protos_len - */ - int struct_version; - - /** The file in PEM format containing the public digital certificates trusted by the client. */ - const char* trustStore; - - /** The file in PEM format containing the public certificate chain of the client. It may also include - * the client's private key. - */ - const char* keyStore; - - /** If not included in the sslKeyStore, this setting points to the file in PEM format containing - * the client's private key. - */ - const char* privateKey; - - /** The password to load the client's privateKey if encrypted. */ - const char* privateKeyPassword; - - /** - * The list of cipher suites that the client will present to the server during the SSL handshake. For a - * full explanation of the cipher list format, please see the OpenSSL on-line documentation: - * http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT - * If this setting is ommitted, its default value will be "ALL", that is, all the cipher suites -excluding - * those offering no encryption- will be considered. - * This setting can be used to set an SSL anonymous connection ("aNULL" string value, for instance). - */ - const char* enabledCipherSuites; - - /** True/False option to enable verification of the server certificate **/ - int enableServerCertAuth; - - /** The SSL/TLS version to use. Specify one of MQTT_SSL_VERSION_DEFAULT (0), - * MQTT_SSL_VERSION_TLS_1_0 (1), MQTT_SSL_VERSION_TLS_1_1 (2) or MQTT_SSL_VERSION_TLS_1_2 (3). - * Only used if struct_version is >= 1. - */ - int sslVersion; - - /** - * Whether to carry out post-connect checks, including that a certificate - * matches the given host name. - * Exists only if struct_version >= 2 - */ - int verify; - - /** - * From the OpenSSL documentation: - * If CApath is not NULL, it points to a directory containing CA certificates in PEM format. - * Exists only if struct_version >= 2 - */ - const char* CApath; - - /** - * Callback function for OpenSSL error handler ERR_print_errors_cb - * Exists only if struct_version >= 3 - */ - int (*ssl_error_cb) (const char *str, size_t len, void *u); - - /** - * Application-specific contex for OpenSSL error handler ERR_print_errors_cb - * Exists only if struct_version >= 3 - */ - void* ssl_error_context; - - /** - * Callback function for setting TLS-PSK options. Parameters correspond to that of - * SSL_CTX_set_psk_client_callback, except for u which is the pointer ssl_psk_context. - * Exists only if struct_version >= 4 - */ - unsigned int (*ssl_psk_cb) (const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len, void *u); - - /** - * Application-specific contex for ssl_psk_cb - * Exists only if struct_version >= 4 - */ - void* ssl_psk_context; - - /** - * Don't load default SSL CA. Should be used together with PSK to make sure - * regular servers with certificate in place is not accepted. - * Exists only if struct_version >= 4 - */ - int disableDefaultTrustStore; - - /** - * The protocol-lists must be in wire-format, which is defined as a vector of non-empty, 8-bit length-prefixed, byte strings. - * The length-prefix byte is not included in the length. Each string is limited to 255 bytes. A byte-string length of 0 is invalid. - * A truncated byte-string is invalid. - * Check documentation for SSL_CTX_set_alpn_protos - * Exists only if struct_version >= 5 - */ - const unsigned char *protos; - - /** - * The length of the vector protos vector - * Exists only if struct_version >= 5 - */ - unsigned int protos_len; -} MQTTAsync_SSLOptions; - -#define MQTTAsync_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 5, NULL, NULL, NULL, NULL, NULL, 1, MQTT_SSL_VERSION_DEFAULT, 0, NULL, NULL, NULL, NULL, NULL, 0, NULL, 0 } - -/** Utility structure where name/value pairs are needed */ -typedef struct -{ - const char* name; /**< name string */ - const char* value; /**< value string */ -} MQTTAsync_nameValue; - -/** - * MQTTAsync_connectOptions defines several settings that control the way the - * client connects to an MQTT server. - * - * Suitable default values are set in the following initializers: - * - MQTTAsync_connectOptions_initializer: for MQTT 3.1.1 non-WebSockets - * - MQTTAsync_connectOptions_initializer5: for MQTT 5.0 non-WebSockets - * - MQTTAsync_connectOptions_initializer_ws: for MQTT 3.1.1 WebSockets - * - MQTTAsync_connectOptions_initializer5_ws: for MQTT 5.0 WebSockets - */ -typedef struct -{ - /** The eyecatcher for this structure. must be MQTC. */ - char struct_id[4]; - /** The version number of this structure. Must be 0, 1, 2, 3 4 5 6, 7 or 8. - * 0 signifies no SSL options and no serverURIs - * 1 signifies no serverURIs - * 2 signifies no MQTTVersion - * 3 signifies no automatic reconnect options - * 4 signifies no binary password option (just string) - * 5 signifies no MQTTV5 properties - * 6 signifies no HTTP headers option - * 7 signifies no HTTP proxy and HTTPS proxy options - */ - int struct_version; - /** The "keep alive" interval, measured in seconds, defines the maximum time - * that should pass without communication between the client and the server - * The client will ensure that at least one message travels across the - * network within each keep alive period. In the absence of a data-related - * message during the time period, the client sends a very small MQTT - * "ping" message, which the server will acknowledge. The keep alive - * interval enables the client to detect when the server is no longer - * available without having to wait for the long TCP/IP timeout. - * Set to 0 if you do not want any keep alive processing. - */ - int keepAliveInterval; - /** - * This is a boolean value. The cleansession setting controls the behaviour - * of both the client and the server at connection and disconnection time. - * The client and server both maintain session state information. This - * information is used to ensure "at least once" and "exactly once" - * delivery, and "exactly once" receipt of messages. Session state also - * includes subscriptions created by an MQTT client. You can choose to - * maintain or discard state information between sessions. - * - * When cleansession is true, the state information is discarded at - * connect and disconnect. Setting cleansession to false keeps the state - * information. When you connect an MQTT client application with - * MQTTAsync_connect(), the client identifies the connection using the - * client identifier and the address of the server. The server checks - * whether session information for this client - * has been saved from a previous connection to the server. If a previous - * session still exists, and cleansession=true, then the previous session - * information at the client and server is cleared. If cleansession=false, - * the previous session is resumed. If no previous session exists, a new - * session is started. - */ - int cleansession; - /** - * This controls how many messages can be in-flight simultaneously. - */ - int maxInflight; - /** - * This is a pointer to an MQTTAsync_willOptions structure. If your - * application does not make use of the Last Will and Testament feature, - * set this pointer to NULL. - */ - MQTTAsync_willOptions* will; - /** - * MQTT servers that support the MQTT v3.1 protocol provide authentication - * and authorisation by user name and password. This is the user name - * parameter. - */ - const char* username; - /** - * MQTT servers that support the MQTT v3.1 protocol provide authentication - * and authorisation by user name and password. This is the password - * parameter. - */ - const char* password; - /** - * The time interval in seconds to allow a connect to complete. - */ - int connectTimeout; - /** - * The time interval in seconds after which unacknowledged publish requests are - * retried during a TCP session. With MQTT 3.1.1 and later, retries are - * not required except on reconnect. 0 turns off in-session retries, and is the - * recommended setting. Adding retries to an already overloaded network only - * exacerbates the problem. - */ - int retryInterval; - /** - * This is a pointer to an MQTTAsync_SSLOptions structure. If your - * application does not make use of SSL, set this pointer to NULL. - */ - MQTTAsync_SSLOptions* ssl; - /** - * A pointer to a callback function to be called if the connect successfully - * completes. Can be set to NULL, in which case no indication of successful - * completion will be received. - */ - MQTTAsync_onSuccess* onSuccess; - /** - * A pointer to a callback function to be called if the connect fails. - * Can be set to NULL, in which case no indication of unsuccessful - * completion will be received. - */ - MQTTAsync_onFailure* onFailure; - /** - * A pointer to any application-specific context. The - * the context pointer is passed to success or failure callback functions to - * provide access to the context information in the callback. - */ - void* context; - /** - * The number of entries in the serverURIs array. - */ - int serverURIcount; - /** - * An array of null-terminated strings specifying the servers to - * which the client will connect. Each string takes the form protocol://host:port. - * protocol must be tcp, ssl, ws or wss. - * The TLS enabled prefixes (ssl, wss) are only valid if a TLS version of the library - * is linked with. - * For host, you can - * specify either an IP address or a domain name. For instance, to connect to - * a server running on the local machines with the default MQTT port, specify - * tcp://localhost:1883. - */ - char* const* serverURIs; - /** - * Sets the version of MQTT to be used on the connect. - * MQTTVERSION_DEFAULT (0) = default: start with 3.1.1, and if that fails, fall back to 3.1 - * MQTTVERSION_3_1 (3) = only try version 3.1 - * MQTTVERSION_3_1_1 (4) = only try version 3.1.1 - */ - int MQTTVersion; - /** - * Reconnect automatically in the case of a connection being lost. 0=false, 1=true - */ - int automaticReconnect; - /** - * The minimum automatic reconnect retry interval in seconds. Doubled on each failed retry. - */ - int minRetryInterval; - /** - * The maximum automatic reconnect retry interval in seconds. The doubling stops here on failed retries. - */ - int maxRetryInterval; - /** - * Optional binary password. Only checked and used if the password option is NULL - */ - struct { - int len; /**< binary password length */ - const void* data; /**< binary password data */ - } binarypwd; - /* - * MQTT V5 clean start flag. Only clears state at the beginning of the session. - */ - int cleanstart; - /** - * MQTT V5 properties for connect - */ - MQTTProperties *connectProperties; - /** - * MQTT V5 properties for the will message in the connect - */ - MQTTProperties *willProperties; - /** - * A pointer to a callback function to be called if the connect successfully - * completes. Can be set to NULL, in which case no indication of successful - * completion will be received. - */ - MQTTAsync_onSuccess5* onSuccess5; - /** - * A pointer to a callback function to be called if the connect fails. - * Can be set to NULL, in which case no indication of unsuccessful - * completion will be received. - */ - MQTTAsync_onFailure5* onFailure5; - /** - * HTTP headers for websockets - */ - const MQTTAsync_nameValue* httpHeaders; - /** - * HTTP proxy - */ - const char* httpProxy; - /** - * HTTPS proxy - */ - const char* httpsProxy; -} MQTTAsync_connectOptions; - -/** Initializer for connect options for MQTT 3.1.1 non-WebSocket connections */ -#define MQTTAsync_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 8, 60, 1, 65535, NULL, NULL, NULL, 30, 0,\ -NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_DEFAULT, 0, 1, 60, {0, NULL}, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL} - -/** Initializer for connect options for MQTT 5.0 non-WebSocket connections */ -#define MQTTAsync_connectOptions_initializer5 { {'M', 'Q', 'T', 'C'}, 8, 60, 0, 65535, NULL, NULL, NULL, 30, 0,\ -NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_5, 0, 1, 60, {0, NULL}, 1, NULL, NULL, NULL, NULL, NULL, NULL, NULL} - -/** Initializer for connect options for MQTT 3.1.1 WebSockets connections. - * The keepalive interval is set to 45 seconds to avoid webserver 60 second inactivity timeouts. - */ -#define MQTTAsync_connectOptions_initializer_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 1, 65535, NULL, NULL, NULL, 30, 0,\ -NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_DEFAULT, 0, 1, 60, {0, NULL}, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL} - -/** Initializer for connect options for MQTT 5.0 WebSockets connections. - * The keepalive interval is set to 45 seconds to avoid webserver 60 second inactivity timeouts. - */ -#define MQTTAsync_connectOptions_initializer5_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 0, 65535, NULL, NULL, NULL, 30, 0,\ -NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_5, 0, 1, 60, {0, NULL}, 1, NULL, NULL, NULL, NULL, NULL, NULL, NULL} - - -/** - * This function attempts to connect a previously-created client (see - * MQTTAsync_create()) to an MQTT server using the specified options. If you - * want to enable asynchronous message and status notifications, you must call - * MQTTAsync_setCallbacks() prior to MQTTAsync_connect(). - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param options A pointer to a valid MQTTAsync_connectOptions - * structure. - * @return ::MQTTASYNC_SUCCESS if the client connect request was accepted. - * If the client was unable to connect to the server, an error code is - * returned via the onFailure callback, if set. - * Error codes greater than 0 are returned by the MQTT protocol:

- * 1: Connection refused: Unacceptable protocol version
- * 2: Connection refused: Identifier rejected
- * 3: Connection refused: Server unavailable
- * 4: Connection refused: Bad user name or password
- * 5: Connection refused: Not authorized
- * 6-255: Reserved for future use
- */ -LIBMQTT_API int MQTTAsync_connect(MQTTAsync handle, const MQTTAsync_connectOptions* options); - -/** Options for the ::MQTTAsync_disconnect call */ -typedef struct -{ - /** The eyecatcher for this structure. Must be MQTD. */ - char struct_id[4]; - /** The version number of this structure. Must be 0 or 1. 0 signifies no V5 properties */ - int struct_version; - /** - * The client delays disconnection for up to this time (in - * milliseconds) in order to allow in-flight message transfers to complete. - */ - int timeout; - /** - * A pointer to a callback function to be called if the disconnect successfully - * completes. Can be set to NULL, in which case no indication of successful - * completion will be received. - */ - MQTTAsync_onSuccess* onSuccess; - /** - * A pointer to a callback function to be called if the disconnect fails. - * Can be set to NULL, in which case no indication of unsuccessful - * completion will be received. - */ - MQTTAsync_onFailure* onFailure; - /** - * A pointer to any application-specific context. The - * the context pointer is passed to success or failure callback functions to - * provide access to the context information in the callback. - */ - void* context; - /** - * MQTT V5 input properties - */ - MQTTProperties properties; - /** - * Reason code for MQTTV5 disconnect - */ - enum MQTTReasonCodes reasonCode; - /** - * A pointer to a callback function to be called if the disconnect successfully - * completes. Can be set to NULL, in which case no indication of successful - * completion will be received. - */ - MQTTAsync_onSuccess5* onSuccess5; - /** - * A pointer to a callback function to be called if the disconnect fails. - * Can be set to NULL, in which case no indication of unsuccessful - * completion will be received. - */ - MQTTAsync_onFailure5* onFailure5; -} MQTTAsync_disconnectOptions; - -#define MQTTAsync_disconnectOptions_initializer { {'M', 'Q', 'T', 'D'}, 0, 0, NULL, NULL, NULL,\ - MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL, NULL } - -#define MQTTAsync_disconnectOptions_initializer5 { {'M', 'Q', 'T', 'D'}, 1, 0, NULL, NULL, NULL,\ - MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL, NULL } - -/** - * This function attempts to disconnect the client from the MQTT - * server. In order to allow the client time to complete handling of messages - * that are in-flight when this function is called, a timeout period is - * specified. When the timeout period has expired, the client disconnects even - * if there are still outstanding message acknowledgements. - * The next time the client connects to the same server, any QoS 1 or 2 - * messages which have not completed will be retried depending on the - * cleansession settings for both the previous and the new connection (see - * MQTTAsync_connectOptions.cleansession and MQTTAsync_connect()). - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param options The client delays disconnection for up to this time (in - * milliseconds) in order to allow in-flight message transfers to complete. - * @return ::MQTTASYNC_SUCCESS if the client successfully disconnects from - * the server. An error code is returned if the client was unable to disconnect - * from the server - */ -LIBMQTT_API int MQTTAsync_disconnect(MQTTAsync handle, const MQTTAsync_disconnectOptions* options); - - -/** - * This function allows the client application to test whether or not a - * client is currently connected to the MQTT server. - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @return Boolean true if the client is connected, otherwise false. - */ -LIBMQTT_API int MQTTAsync_isConnected(MQTTAsync handle); - - -/** - * This function attempts to subscribe a client to a single topic, which may - * contain wildcards (see @ref wildcard). This call also specifies the - * @ref qos requested for the subscription - * (see also MQTTAsync_subscribeMany()). - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param topic The subscription topic, which may include wildcards. - * @param qos The requested quality of service for the subscription. - * @param response A pointer to a response options structure. Used to set callback functions. - * @return ::MQTTASYNC_SUCCESS if the subscription request is successful. - * An error code is returned if there was a problem registering the - * subscription. - */ -LIBMQTT_API int MQTTAsync_subscribe(MQTTAsync handle, const char* topic, int qos, MQTTAsync_responseOptions* response); - - -/** - * This function attempts to subscribe a client to a list of topics, which may - * contain wildcards (see @ref wildcard). This call also specifies the - * @ref qos requested for each topic (see also MQTTAsync_subscribe()). - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param count The number of topics for which the client is requesting - * subscriptions. - * @param topic An array (of length count) of pointers to - * topics, each of which may include wildcards. - * @param qos An array (of length count) of @ref qos - * values. qos[n] is the requested QoS for topic[n]. - * @param response A pointer to a response options structure. Used to set callback functions. - * @return ::MQTTASYNC_SUCCESS if the subscription request is successful. - * An error code is returned if there was a problem registering the - * subscriptions. - */ -LIBMQTT_API int MQTTAsync_subscribeMany(MQTTAsync handle, int count, char* const* topic, const int* qos, MQTTAsync_responseOptions* response); - -/** - * This function attempts to remove an existing subscription made by the - * specified client. - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param topic The topic for the subscription to be removed, which may - * include wildcards (see @ref wildcard). - * @param response A pointer to a response options structure. Used to set callback functions. - * @return ::MQTTASYNC_SUCCESS if the subscription is removed. - * An error code is returned if there was a problem removing the - * subscription. - */ -LIBMQTT_API int MQTTAsync_unsubscribe(MQTTAsync handle, const char* topic, MQTTAsync_responseOptions* response); - -/** - * This function attempts to remove existing subscriptions to a list of topics - * made by the specified client. - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param count The number subscriptions to be removed. - * @param topic An array (of length count) of pointers to the topics of - * the subscriptions to be removed, each of which may include wildcards. - * @param response A pointer to a response options structure. Used to set callback functions. - * @return ::MQTTASYNC_SUCCESS if the subscriptions are removed. - * An error code is returned if there was a problem removing the subscriptions. - */ -LIBMQTT_API int MQTTAsync_unsubscribeMany(MQTTAsync handle, int count, char* const* topic, MQTTAsync_responseOptions* response); - - -/** - * This function attempts to publish a message to a given topic (see also - * ::MQTTAsync_sendMessage()). An ::MQTTAsync_token is issued when - * this function returns successfully if the QoS is greater than 0. - * If the client application needs to - * test for successful delivery of messages, a callback should be set - * (see ::MQTTAsync_onSuccess() and ::MQTTAsync_deliveryComplete()). - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param destinationName The topic associated with this message. - * @param payloadlen The length of the payload in bytes. - * @param payload A pointer to the byte array payload of the message. - * @param qos The @ref qos of the message. - * @param retained The retained flag for the message. - * @param response A pointer to an ::MQTTAsync_responseOptions structure. Used to set callback functions. - * This is optional and can be set to NULL. - * @return ::MQTTASYNC_SUCCESS if the message is accepted for publication. - * An error code is returned if there was a problem accepting the message. - */ -LIBMQTT_API int MQTTAsync_send(MQTTAsync handle, const char* destinationName, int payloadlen, const void* payload, int qos, - int retained, MQTTAsync_responseOptions* response); - -/** - * This function attempts to publish a message to a given topic (see also - * MQTTAsync_publish()). An ::MQTTAsync_token is issued when - * this function returns successfully if the QoS is greater than 0. - * If the client application needs to - * test for successful delivery of messages, a callback should be set - * (see ::MQTTAsync_onSuccess() and ::MQTTAsync_deliveryComplete()). - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param destinationName The topic associated with this message. - * @param msg A pointer to a valid MQTTAsync_message structure containing - * the payload and attributes of the message to be published. - * @param response A pointer to an ::MQTTAsync_responseOptions structure. Used to set callback functions. - * @return ::MQTTASYNC_SUCCESS if the message is accepted for publication. - * An error code is returned if there was a problem accepting the message. - */ -LIBMQTT_API int MQTTAsync_sendMessage(MQTTAsync handle, const char* destinationName, const MQTTAsync_message* msg, MQTTAsync_responseOptions* response); - - -/** - * This function sets a pointer to an array of tokens for - * messages that are currently in-flight (pending completion). - * - * Important note: The memory used to hold the array of tokens is - * malloc()'d in this function. The client application is responsible for - * freeing this memory when it is no longer required. - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param tokens The address of a pointer to an ::MQTTAsync_token. - * When the function returns successfully, the pointer is set to point to an - * array of tokens representing messages pending completion. The last member of - * the array is set to -1 to indicate there are no more tokens. If no tokens - * are pending, the pointer is set to NULL. - * @return ::MQTTASYNC_SUCCESS if the function returns successfully. - * An error code is returned if there was a problem obtaining the list of - * pending tokens. - */ -LIBMQTT_API int MQTTAsync_getPendingTokens(MQTTAsync handle, MQTTAsync_token **tokens); - -/** - * Tests whether a request corresponding to a token is complete. - * - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param token An ::MQTTAsync_token associated with a request. - * @return 1 if the request has been completed, 0 if not. - */ -#define MQTTASYNC_TRUE 1 -LIBMQTT_API int MQTTAsync_isComplete(MQTTAsync handle, MQTTAsync_token token); - - -/** - * Waits for a request corresponding to a token to complete. This only works for - * messages with QoS greater than 0. A QoS 0 message has no MQTT token. - * This function will always return ::MQTTASYNC_SUCCESS for a QoS 0 message. - * - * @param handle A valid client handle from a successful call to - * MQTTAsync_create(). - * @param token An ::MQTTAsync_token associated with a request. - * @param timeout the maximum time to wait for completion, in milliseconds - * @return ::MQTTASYNC_SUCCESS if the request has been completed in the time allocated, - * ::MQTTASYNC_FAILURE or ::MQTTASYNC_DISCONNECTED if not. - */ -LIBMQTT_API int MQTTAsync_waitForCompletion(MQTTAsync handle, MQTTAsync_token token, unsigned long timeout); - - -/** - * This function frees memory allocated to an MQTT message, including the - * additional memory allocated to the message payload. The client application - * calls this function when the message has been fully processed. Important - * note: This function does not free the memory allocated to a message - * topic string. It is the responsibility of the client application to free - * this memory using the MQTTAsync_free() library function. - * @param msg The address of a pointer to the ::MQTTAsync_message structure - * to be freed. - */ -LIBMQTT_API void MQTTAsync_freeMessage(MQTTAsync_message** msg); - -/** - * This function frees memory allocated by the MQTT C client library, especially the - * topic name. This is needed on Windows when the client library and application - * program have been compiled with different versions of the C compiler. It is - * thus good policy to always use this function when freeing any MQTT C client- - * allocated memory. - * @param ptr The pointer to the client library storage to be freed. - */ -LIBMQTT_API void MQTTAsync_free(void* ptr); - -/** - * This function is used to allocate memory to be used or freed by the MQTT C client library, - * especially the data in the ::MQTTPersistence_afterRead and ::MQTTPersistence_beforeWrite - * callbacks. This is needed on Windows when the client library and application - * program have been compiled with different versions of the C compiler. - * @param size The size of the memory to be allocated. - */ -LIBMQTT_API void* MQTTAsync_malloc(size_t size); - -/** - * This function frees the memory allocated to an MQTT client (see - * MQTTAsync_create()). It should be called when the client is no longer - * required. - * @param handle A pointer to the handle referring to the ::MQTTAsync - * structure to be freed. - */ -LIBMQTT_API void MQTTAsync_destroy(MQTTAsync* handle); - - - -enum MQTTASYNC_TRACE_LEVELS -{ - MQTTASYNC_TRACE_MAXIMUM = 1, - MQTTASYNC_TRACE_MEDIUM, - MQTTASYNC_TRACE_MINIMUM, - MQTTASYNC_TRACE_PROTOCOL, - MQTTASYNC_TRACE_ERROR, - MQTTASYNC_TRACE_SEVERE, - MQTTASYNC_TRACE_FATAL, -}; - - -/** - * This function sets the level of trace information which will be - * returned in the trace callback. - * @param level the trace level required - */ -LIBMQTT_API void MQTTAsync_setTraceLevel(enum MQTTASYNC_TRACE_LEVELS level); - - -/** - * This is a callback function prototype which must be implemented if you want - * to receive trace information. Do not invoke any other Paho API calls in this - * callback function - unpredictable behavior may result. - * @param level the trace level of the message returned - * @param message the trace message. This is a pointer to a static buffer which - * will be overwritten on each call. You must copy the data if you want to keep - * it for later. - */ -typedef void MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char* message); - -/** - * This function sets the trace callback if needed. If set to NULL, - * no trace information will be returned. The default trace level is - * MQTTASYNC_TRACE_MINIMUM. - * @param callback a pointer to the function which will handle the trace information - */ -LIBMQTT_API void MQTTAsync_setTraceCallback(MQTTAsync_traceCallback* callback); - -/** - * This function returns version information about the library. - * no trace information will be returned. The default trace level is - * MQTTASYNC_TRACE_MINIMUM - * @return an array of strings describing the library. The last entry is a NULL pointer. - */ -LIBMQTT_API MQTTAsync_nameValue* MQTTAsync_getVersionInfo(void); - -/** - * Returns a pointer to a string representation of the error code, or NULL. - * Do not free after use. Returns NULL if the error code is unknown. - * @param code the MQTTASYNC_ return code. - * @return a static string representation of the error code. - */ -LIBMQTT_API const char* MQTTAsync_strerror(int code); - - -/*! - * @cond MQTTAsync_main - * @page async Threading - * The client application runs on several threads. - * Processing of handshaking and maintaining - * the network connection is performed in the background. - * This API is thread safe: functions may be called by multiple application - * threads. - * Notifications of status and message reception are provided to the client - * application using callbacks registered with the library by the call to - * MQTTAsync_setCallbacks() (see MQTTAsync_messageArrived(), - * MQTTAsync_connectionLost() and MQTTAsync_deliveryComplete()). - * In addition, some functions allow success and failure callbacks to be set - * for individual requests, in the ::MQTTAsync_responseOptions structure. Applications - * can be written as a chain of callback functions. - * - * @page callbacks Callbacks - * Any function from this API may be used within a callback. It is not advisable to - * use ::MQTTAsync_waitForCompletion within a callback, however, as it is the only - * API call that may take some time to complete, which may cause unpredictable - * behaviour. All the other API calls are intended to complete quickly, starting - * a request in the background, with success or failure notified by other callbacks. - * - * If no callbacks are assigned, this will include the message arrived callback. - * This could be done if the application is a pure publisher, and does - * not subscribe to any topics. If however messages are received, and no message - * arrived callback is set, then those messages will accumulate - * and take up memory, as there is no place for them to be delivered. - * A log message will be written to highlight the issue, but it is up - * to the application to protect against this situation. - * - * @page auto_reconnect Automatic Reconnect - * The ability for the client library to reconnect automatically in the event - * of a connection failure was added in 1.1. The connection lost callback - * allows a flexible response to the loss of a connection, so almost any - * behaviour can be implemented in that way. Automatic reconnect does have the - * advantage of being a little simpler to use. - * - * To switch on automatic reconnect, the connect options field - * automaticReconnect should be set to non-zero. The minimum and maximum times - * before the next connection attempt can also be set, the defaults being 1 and - * 60 seconds. At each failure to reconnect, the retry interval is doubled until - * the maximum value is reached, and there it stays until the connection is - * successfully re-established whereupon it is reset. - * - * When a reconnection attempt is successful, the ::MQTTAsync_connected callback - * function is invoked, if set by calling ::MQTTAsync_setConnected. This allows - * the application to take any actions needed, such as amending subscriptions. - * - * @page offline_publish Publish While Disconnected - * This feature was not originally available because with persistence enabled, - * messages could be stored locally without ever knowing if they could be sent. - * The client application could have created the client with an erroneous broker - * address or port for instance. - * - * To enable messages to be published when the application is disconnected - * ::MQTTAsync_createWithOptions must be used instead of ::MQTTAsync_create to - * create the client object. The ::MQTTAsync_createOptions field sendWhileDisconnected - * must be set to non-zero, and the maxBufferedMessages field set as required - - * the default being 100. - * - * ::MQTTAsync_getPendingTokens can be called to return the ids of the messages - * waiting to be sent, or for which the sending process has not completed. - * - * @page wildcard Subscription wildcards - * Every MQTT message includes a topic that classifies it. MQTT servers use - * topics to determine which subscribers should receive messages published to - * the server. - * - * Consider the server receiving messages from several environmental sensors. - * Each sensor publishes its measurement data as a message with an associated - * topic. Subscribing applications need to know which sensor originally - * published each received message. A unique topic is thus used to identify - * each sensor and measurement type. Topics such as SENSOR1TEMP, - * SENSOR1HUMIDITY, SENSOR2TEMP and so on achieve this but are not very - * flexible. If additional sensors are added to the system at a later date, - * subscribing applications must be modified to receive them. - * - * To provide more flexibility, MQTT supports a hierarchical topic namespace. - * This allows application designers to organize topics to simplify their - * management. Levels in the hierarchy are delimited by the '/' character, - * such as SENSOR/1/HUMIDITY. Publishers and subscribers use these - * hierarchical topics as already described. - * - * For subscriptions, two wildcard characters are supported: - * - * Publishers are not allowed to use the wildcard characters in their topic - * names. - * - * Deciding on your topic hierarchy is an important step in your system design. - * - * @page qos Quality of service - * The MQTT protocol provides three qualities of service for delivering - * messages between clients and servers: "at most once", "at least once" and - * "exactly once". - * - * Quality of service (QoS) is an attribute of an individual message being - * published. An application sets the QoS for a specific message by setting the - * MQTTAsync_message.qos field to the required value. - * - * A subscribing client can set the maximum quality of service a server uses - * to send messages that match the client subscriptions. The - * MQTTAsync_subscribe() and MQTTAsync_subscribeMany() functions set this - * maximum. The QoS of a message forwarded to a subscriber thus might be - * different to the QoS given to the message by the original publisher. - * The lower of the two values is used to forward a message. - * - * The three levels are: - * - * QoS0, At most once: The message is delivered at most once, or it - * may not be delivered at all. Its delivery across the network is not - * acknowledged. The message is not stored. The message could be lost if the - * client is disconnected, or if the server fails. QoS0 is the fastest mode of - * transfer. It is sometimes called "fire and forget". - * - * The MQTT protocol does not require servers to forward publications at QoS0 - * to a client. If the client is disconnected at the time the server receives - * the publication, the publication might be discarded, depending on the - * server implementation. - * - * QoS1, At least once: The message is always delivered at least once. - * It might be delivered multiple times if there is a failure before an - * acknowledgment is received by the sender. The message must be stored - * locally at the sender, until the sender receives confirmation that the - * message has been published by the receiver. The message is stored in case - * the message must be sent again. - * - * QoS2, Exactly once: The message is always delivered exactly once. - * The message must be stored locally at the sender, until the sender receives - * confirmation that the message has been published by the receiver. The - * message is stored in case the message must be sent again. QoS2 is the - * safest, but slowest mode of transfer. A more sophisticated handshaking - * and acknowledgement sequence is used than for QoS1 to ensure no duplication - * of messages occurs. - * @page publish Publication example -@code -#include -#include -#include -#include "MQTTAsync.h" - -#if !defined(_WIN32) -#include -#else -#include -#endif - -#if defined(_WRS_KERNEL) -#include -#endif - -#define ADDRESS "tcp://mqtt.eclipseprojects.io:1883" -#define CLIENTID "ExampleClientPub" -#define TOPIC "MQTT Examples" -#define PAYLOAD "Hello World!" -#define QOS 1 -#define TIMEOUT 10000L - -int finished = 0; - -void connlost(void *context, char *cause) -{ - MQTTAsync client = (MQTTAsync)context; - MQTTAsync_connectOptions conn_opts = MQTTAsync_connectOptions_initializer; - int rc; - - printf("\nConnection lost\n"); - printf(" cause: %s\n", cause); - - printf("Reconnecting\n"); - conn_opts.keepAliveInterval = 20; - conn_opts.cleansession = 1; - if ((rc = MQTTAsync_connect(client, &conn_opts)) != MQTTASYNC_SUCCESS) - { - printf("Failed to start connect, return code %d\n", rc); - finished = 1; - } -} - -void onDisconnectFailure(void* context, MQTTAsync_failureData* response) -{ - printf("Disconnect failed\n"); - finished = 1; -} - -void onDisconnect(void* context, MQTTAsync_successData* response) -{ - printf("Successful disconnection\n"); - finished = 1; -} - -void onSendFailure(void* context, MQTTAsync_failureData* response) -{ - MQTTAsync client = (MQTTAsync)context; - MQTTAsync_disconnectOptions opts = MQTTAsync_disconnectOptions_initializer; - int rc; - - printf("Message send failed token %d error code %d\n", response->token, response->code); - opts.onSuccess = onDisconnect; - opts.onFailure = onDisconnectFailure; - opts.context = client; - if ((rc = MQTTAsync_disconnect(client, &opts)) != MQTTASYNC_SUCCESS) - { - printf("Failed to start disconnect, return code %d\n", rc); - exit(EXIT_FAILURE); - } -} - -void onSend(void* context, MQTTAsync_successData* response) -{ - MQTTAsync client = (MQTTAsync)context; - MQTTAsync_disconnectOptions opts = MQTTAsync_disconnectOptions_initializer; - int rc; - - printf("Message with token value %d delivery confirmed\n", response->token); - opts.onSuccess = onDisconnect; - opts.onFailure = onDisconnectFailure; - opts.context = client; - if ((rc = MQTTAsync_disconnect(client, &opts)) != MQTTASYNC_SUCCESS) - { - printf("Failed to start disconnect, return code %d\n", rc); - exit(EXIT_FAILURE); - } -} - - -void onConnectFailure(void* context, MQTTAsync_failureData* response) -{ - printf("Connect failed, rc %d\n", response ? response->code : 0); - finished = 1; -} - - -void onConnect(void* context, MQTTAsync_successData* response) -{ - MQTTAsync client = (MQTTAsync)context; - MQTTAsync_responseOptions opts = MQTTAsync_responseOptions_initializer; - MQTTAsync_message pubmsg = MQTTAsync_message_initializer; - int rc; - - printf("Successful connection\n"); - opts.onSuccess = onSend; - opts.onFailure = onSendFailure; - opts.context = client; - pubmsg.payload = PAYLOAD; - pubmsg.payloadlen = (int)strlen(PAYLOAD); - pubmsg.qos = QOS; - pubmsg.retained = 0; - if ((rc = MQTTAsync_sendMessage(client, TOPIC, &pubmsg, &opts)) != MQTTASYNC_SUCCESS) - { - printf("Failed to start sendMessage, return code %d\n", rc); - exit(EXIT_FAILURE); - } -} - -int messageArrived(void* context, char* topicName, int topicLen, MQTTAsync_message* m) -{ - // not expecting any messages - return 1; -} - -int main(int argc, char* argv[]) -{ - MQTTAsync client; - MQTTAsync_connectOptions conn_opts = MQTTAsync_connectOptions_initializer; - int rc; - - if ((rc = MQTTAsync_create(&client, ADDRESS, CLIENTID, MQTTCLIENT_PERSISTENCE_NONE, NULL)) != MQTTASYNC_SUCCESS) - { - printf("Failed to create client object, return code %d\n", rc); - exit(EXIT_FAILURE); - } - - if ((rc = MQTTAsync_setCallbacks(client, NULL, connlost, messageArrived, NULL)) != MQTTASYNC_SUCCESS) - { - printf("Failed to set callback, return code %d\n", rc); - exit(EXIT_FAILURE); - } - - conn_opts.keepAliveInterval = 20; - conn_opts.cleansession = 1; - conn_opts.onSuccess = onConnect; - conn_opts.onFailure = onConnectFailure; - conn_opts.context = client; - if ((rc = MQTTAsync_connect(client, &conn_opts)) != MQTTASYNC_SUCCESS) - { - printf("Failed to start connect, return code %d\n", rc); - exit(EXIT_FAILURE); - } - - printf("Waiting for publication of %s\n" - "on topic %s for client with ClientID: %s\n", - PAYLOAD, TOPIC, CLIENTID); - while (!finished) - #if defined(_WIN32) - Sleep(100); - #else - usleep(10000L); - #endif - - MQTTAsync_destroy(&client); - return rc; -} - - * @endcode - * @page subscribe Subscription example -@code -#include -#include -#include -#include "MQTTAsync.h" - -#if !defined(_WIN32) -#include -#else -#include -#endif - -#if defined(_WRS_KERNEL) -#include -#endif - -#define ADDRESS "tcp://mqtt.eclipseprojects.io:1883" -#define CLIENTID "ExampleClientSub" -#define TOPIC "MQTT Examples" -#define PAYLOAD "Hello World!" -#define QOS 1 -#define TIMEOUT 10000L - -int disc_finished = 0; -int subscribed = 0; -int finished = 0; - -void connlost(void *context, char *cause) -{ - MQTTAsync client = (MQTTAsync)context; - MQTTAsync_connectOptions conn_opts = MQTTAsync_connectOptions_initializer; - int rc; - - printf("\nConnection lost\n"); - if (cause) - printf(" cause: %s\n", cause); - - printf("Reconnecting\n"); - conn_opts.keepAliveInterval = 20; - conn_opts.cleansession = 1; - if ((rc = MQTTAsync_connect(client, &conn_opts)) != MQTTASYNC_SUCCESS) - { - printf("Failed to start connect, return code %d\n", rc); - finished = 1; - } -} - - -int msgarrvd(void *context, char *topicName, int topicLen, MQTTAsync_message *message) -{ - printf("Message arrived\n"); - printf(" topic: %s\n", topicName); - printf(" message: %.*s\n", message->payloadlen, (char*)message->payload); - MQTTAsync_freeMessage(&message); - MQTTAsync_free(topicName); - return 1; -} - -void onDisconnectFailure(void* context, MQTTAsync_failureData* response) -{ - printf("Disconnect failed, rc %d\n", response->code); - disc_finished = 1; -} - -void onDisconnect(void* context, MQTTAsync_successData* response) -{ - printf("Successful disconnection\n"); - disc_finished = 1; -} - -void onSubscribe(void* context, MQTTAsync_successData* response) -{ - printf("Subscribe succeeded\n"); - subscribed = 1; -} - -void onSubscribeFailure(void* context, MQTTAsync_failureData* response) -{ - printf("Subscribe failed, rc %d\n", response->code); - finished = 1; -} - - -void onConnectFailure(void* context, MQTTAsync_failureData* response) -{ - printf("Connect failed, rc %d\n", response->code); - finished = 1; -} - - -void onConnect(void* context, MQTTAsync_successData* response) -{ - MQTTAsync client = (MQTTAsync)context; - MQTTAsync_responseOptions opts = MQTTAsync_responseOptions_initializer; - int rc; - - printf("Successful connection\n"); - - printf("Subscribing to topic %s\nfor client %s using QoS%d\n\n" - "Press Q to quit\n\n", TOPIC, CLIENTID, QOS); - opts.onSuccess = onSubscribe; - opts.onFailure = onSubscribeFailure; - opts.context = client; - if ((rc = MQTTAsync_subscribe(client, TOPIC, QOS, &opts)) != MQTTASYNC_SUCCESS) - { - printf("Failed to start subscribe, return code %d\n", rc); - finished = 1; - } -} - - -int main(int argc, char* argv[]) -{ - MQTTAsync client; - MQTTAsync_connectOptions conn_opts = MQTTAsync_connectOptions_initializer; - MQTTAsync_disconnectOptions disc_opts = MQTTAsync_disconnectOptions_initializer; - int rc; - int ch; - - if ((rc = MQTTAsync_create(&client, ADDRESS, CLIENTID, MQTTCLIENT_PERSISTENCE_NONE, NULL)) - != MQTTASYNC_SUCCESS) - { - printf("Failed to create client, return code %d\n", rc); - rc = EXIT_FAILURE; - goto exit; - } - - if ((rc = MQTTAsync_setCallbacks(client, client, connlost, msgarrvd, NULL)) != MQTTASYNC_SUCCESS) - { - printf("Failed to set callbacks, return code %d\n", rc); - rc = EXIT_FAILURE; - goto destroy_exit; - } - - conn_opts.keepAliveInterval = 20; - conn_opts.cleansession = 1; - conn_opts.onSuccess = onConnect; - conn_opts.onFailure = onConnectFailure; - conn_opts.context = client; - if ((rc = MQTTAsync_connect(client, &conn_opts)) != MQTTASYNC_SUCCESS) - { - printf("Failed to start connect, return code %d\n", rc); - rc = EXIT_FAILURE; - goto destroy_exit; - } - - while (!subscribed && !finished) - #if defined(_WIN32) - Sleep(100); - #else - usleep(10000L); - #endif - - if (finished) - goto exit; - - do - { - ch = getchar(); - } while (ch!='Q' && ch != 'q'); - - disc_opts.onSuccess = onDisconnect; - disc_opts.onFailure = onDisconnectFailure; - if ((rc = MQTTAsync_disconnect(client, &disc_opts)) != MQTTASYNC_SUCCESS) - { - printf("Failed to start disconnect, return code %d\n", rc); - rc = EXIT_FAILURE; - goto destroy_exit; - } - while (!disc_finished) - { - #if defined(_WIN32) - Sleep(100); - #else - usleep(10000L); - #endif - } - -destroy_exit: - MQTTAsync_destroy(&client); -exit: - return rc; -} - - * @endcode -* @page tracing Tracing - * - * Runtime tracing can be controlled by environment variables or API calls. - * - * #### Environment variables - * - * Tracing is switched on by setting the MQTT_C_CLIENT_TRACE environment variable. - * A value of ON, or stdout, prints to stdout, any other value is interpreted as a file name to use. - * - * The amount of trace detail is controlled with the MQTT_C_CLIENT_TRACE_LEVEL environment - * variable - valid values are ERROR, PROTOCOL, MINIMUM, MEDIUM and MAXIMUM - * (from least to most verbose). - * - * The variable MQTT_C_CLIENT_TRACE_MAX_LINES limits the number of lines of trace that are output - * to a file. Two files are used at most, when they are full, the last one is overwritten with the - * new trace entries. The default size is 1000 lines. - * - * #### Trace API calls - * - * MQTTAsync_traceCallback() is used to set a callback function which is called whenever trace - * information is available. This will be the same information as that printed if the - * environment variables were used to control the trace. - * - * The MQTTAsync_setTraceLevel() calls is used to set the maximum level of trace entries that will be - * passed to the callback function. The levels are: - * 1. ::MQTTASYNC_TRACE_MAXIMUM - * 2. ::MQTTASYNC_TRACE_MEDIUM - * 3. ::MQTTASYNC_TRACE_MINIMUM - * 4. ::MQTTASYNC_TRACE_PROTOCOL - * 5. ::MQTTASYNC_TRACE_ERROR - * 6. ::MQTTASYNC_TRACE_SEVERE - * 7. ::MQTTASYNC_TRACE_FATAL - * - * Selecting ::MQTTASYNC_TRACE_MAXIMUM will cause all trace entries at all levels to be returned. - * Choosing ::MQTTASYNC_TRACE_ERROR will cause ERROR, SEVERE and FATAL trace entries to be returned - * to the callback function. - * - * ### MQTT Packet Tracing - * - * A feature that can be very useful is printing the MQTT packets that are sent and received. To - * achieve this, use the following environment variable settings: - * @code - MQTT_C_CLIENT_TRACE=ON - MQTT_C_CLIENT_TRACE_LEVEL=PROTOCOL - * @endcode - * The output you should see looks like this: - * @code - 20130528 155936.813 3 stdout-subscriber -> CONNECT cleansession: 1 (0) - 20130528 155936.813 3 stdout-subscriber <- CONNACK rc: 0 - 20130528 155936.813 3 stdout-subscriber -> SUBSCRIBE msgid: 1 (0) - 20130528 155936.813 3 stdout-subscriber <- SUBACK msgid: 1 - 20130528 155941.818 3 stdout-subscriber -> DISCONNECT (0) - * @endcode - * where the fields are: - * 1. date - * 2. time - * 3. socket number - * 4. client id - * 5. direction (-> from client to server, <- from server to client) - * 6. packet details - * - * ### Default Level Tracing - * - * This is an extract of a default level trace of a call to connect: - * @code - 19700101 010000.000 (1152206656) (0)> MQTTClient_connect:893 - 19700101 010000.000 (1152206656) (1)> MQTTClient_connectURI:716 - 20130528 160447.479 Connecting to serverURI localhost:1883 - 20130528 160447.479 (1152206656) (2)> MQTTProtocol_connect:98 - 20130528 160447.479 (1152206656) (3)> MQTTProtocol_addressPort:48 - 20130528 160447.479 (1152206656) (3)< MQTTProtocol_addressPort:73 - 20130528 160447.479 (1152206656) (3)> Socket_new:599 - 20130528 160447.479 New socket 4 for localhost, port 1883 - 20130528 160447.479 (1152206656) (4)> Socket_addSocket:163 - 20130528 160447.479 (1152206656) (5)> Socket_setnonblocking:73 - 20130528 160447.479 (1152206656) (5)< Socket_setnonblocking:78 (0) - 20130528 160447.479 (1152206656) (4)< Socket_addSocket:176 (0) - 20130528 160447.479 (1152206656) (4)> Socket_error:95 - 20130528 160447.479 (1152206656) (4)< Socket_error:104 (115) - 20130528 160447.479 Connect pending - 20130528 160447.479 (1152206656) (3)< Socket_new:683 (115) - 20130528 160447.479 (1152206656) (2)< MQTTProtocol_connect:131 (115) - * @endcode - * where the fields are: - * 1. date - * 2. time - * 3. thread id - * 4. function nesting level - * 5. function entry (>) or exit (<) - * 6. function name : line of source code file - * 7. return value (if there is one) - * - * ### Memory Allocation Tracing - * - * Setting the trace level to maximum causes memory allocations and frees to be traced along with - * the default trace entries, with messages like the following: - * @code - 20130528 161819.657 Allocating 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 177 ptr 0x179f930 - - 20130528 161819.657 Freeing 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 201, heap use now 896 bytes - * @endcode - * When the last MQTT client object is destroyed, if the trace is being recorded - * and all memory allocated by the client library has not been freed, an error message will be - * written to the trace. This can help with fixing memory leaks. The message will look like this: - * @code - 20130528 163909.208 Some memory not freed at shutdown, possible memory leak - 20130528 163909.208 Heap scan start, total 880 bytes - 20130528 163909.208 Heap element size 32, line 354, file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c, ptr 0x260cb00 - 20130528 163909.208 Content - 20130528 163909.209 Heap scan end - * @endcode - * @endcond - */ - -#if defined(__cplusplus) - } -#endif - -#endif diff --git a/MQTTClient.h b/MQTTClient.h deleted file mode 100644 index a5dc7f2..0000000 --- a/MQTTClient.h +++ /dev/null @@ -1,1980 +0,0 @@ -/******************************************************************************* - * Copyright (c) 2009, 2023 IBM Corp., Ian Craggs and others - * - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v2.0 - * and Eclipse Distribution License v1.0 which accompany this distribution. - * - * The Eclipse Public License is available at - * https://www.eclipse.org/legal/epl-2.0/ - * and the Eclipse Distribution License is available at - * http://www.eclipse.org/org/documents/edl-v10.php. - * - * Contributors: - * Ian Craggs - initial API and implementation and/or initial documentation - * Ian Craggs, Allan Stockdill-Mander - SSL updates - * Ian Craggs - multiple server connection support - * Ian Craggs - MQTT 3.1.1 support - * Ian Craggs - remove const from eyecatchers #168 - *******************************************************************************/ - -/** - * @cond MQTTClient_internal - * @mainpage MQTT Client Library Internals - * In the beginning there was one MQTT C client library, MQTTClient, as implemented in MQTTClient.c - * This library was designed to be easy to use for applications which didn't mind if some of the calls - * blocked for a while. For instance, the MQTTClient_connect call will block until a successful - * connection has completed, or a connection has failed, which could be as long as the "connection - * timeout" interval, whose default is 30 seconds. - * - * However in mobile devices and other windowing environments, blocking on the GUI thread is a bad - * thing as it causes the user interface to freeze. Hence a new API, MQTTAsync, implemented - * in MQTTAsync.c, was devised. There are no blocking calls in this library, so it is well suited - * to GUI and mobile environments, at the expense of some extra complexity. - * - * Both libraries are designed to be sparing in the use of threads. So multiple client objects are - * handled by one or two threads, with a select call in Socket_getReadySocket(), used to determine - * when a socket has incoming data. This API is thread safe: functions may be called by multiple application - * threads, with the exception of ::MQTTClient_yield and ::MQTTClient_receive, which are intended - * for single threaded environments only. - * - * @endcond - * @cond MQTTClient_main - * @mainpage MQTT Client library for C (MQTTClient) - * © Copyright 2009, 2023 IBM Corp., Ian Craggs and others - * - * @brief An MQTT client library in C. - * - * These pages describe the original more synchronous API which might be - * considered easier to use. Some of the calls will block. For the new - * totally asynchronous API where no calls block, which is especially suitable - * for use in windowed environments, see the - * MQTT C Client Asynchronous API Documentation. - * The MQTTClient API is not thread safe, whereas the MQTTAsync API is. - * - * An MQTT client application connects to MQTT-capable servers. - * A typical client is responsible for collecting information from a telemetry - * device and publishing the information to the server. It can also subscribe - * to topics, receive messages, and use this information to control the - * telemetry device. - * - * MQTT clients implement the published MQTT v3 protocol. You can write your own - * API to the MQTT protocol using the programming language and platform of your - * choice. This can be time-consuming and error-prone. - * - * To simplify writing MQTT client applications, this library encapsulates - * the MQTT v3 protocol for you. Using this library enables a fully functional - * MQTT client application to be written in a few lines of code. - * The information presented here documents the API provided - * by the MQTT Client library for C. - * - * Using the client
- * Applications that use the client library typically use a similar structure: - *
    - *
  • Create a client object
    • - *
  • Set the options to connect to an MQTT server
    • - *
  • Set up callback functions if multi-threaded (asynchronous mode) - * operation is being used (see @ref async).
    • - *
  • Subscribe to any topics the client needs to receive
    • - *
  • Repeat until finished:
    • - *
      - *
    • Publish any messages the client needs to
      • - *
    • Handle any incoming messages
      • - *
    - *
  • Disconnect the client
    • - *
  • Free any memory being used by the client
    • - *
- * Some simple examples are shown here: - *
    - *
  • @ref pubsync
    • - *
  • @ref pubasync
    • - *
  • @ref subasync
    • - *
- * Additional information about important concepts is provided here: - *
    - *
  • @ref async
    • - *
  • @ref callbacks
    • - *
  • @ref wildcard
    • - *
  • @ref qos
    • - *
  • @ref tracing
    • - *
- * @endcond - */ - -/* -/// @cond EXCLUDE -*/ -#if !defined(MQTTCLIENT_H) -#define MQTTCLIENT_H - -#if defined(__cplusplus) - extern "C" { -#endif - -#include -/* -/// @endcond -*/ - -#include "MQTTExportDeclarations.h" - -#include "MQTTProperties.h" -#include "MQTTReasonCodes.h" -#include "MQTTSubscribeOpts.h" -#if !defined(NO_PERSISTENCE) -#include "MQTTClientPersistence.h" -#endif - -/** - * Return code: No error. Indicates successful completion of an MQTT client - * operation. - */ -#define MQTTCLIENT_SUCCESS 0 -/** - * Return code: A generic error code indicating the failure of an MQTT client - * operation. - */ -#define MQTTCLIENT_FAILURE -1 - -/* error code -2 is MQTTCLIENT_PERSISTENCE_ERROR */ - -/** - * Return code: The client is disconnected. - */ -#define MQTTCLIENT_DISCONNECTED -3 -/** - * Return code: The maximum number of messages allowed to be simultaneously - * in-flight has been reached. - */ -#define MQTTCLIENT_MAX_MESSAGES_INFLIGHT -4 -/** - * Return code: An invalid UTF-8 string has been detected. - */ -#define MQTTCLIENT_BAD_UTF8_STRING -5 -/** - * Return code: A NULL parameter has been supplied when this is invalid. - */ -#define MQTTCLIENT_NULL_PARAMETER -6 -/** - * Return code: The topic has been truncated (the topic string includes - * embedded NULL characters). String functions will not access the full topic. - * Use the topic length value to access the full topic. - */ -#define MQTTCLIENT_TOPICNAME_TRUNCATED -7 -/** - * Return code: A structure parameter does not have the correct eyecatcher - * and version number. - */ -#define MQTTCLIENT_BAD_STRUCTURE -8 -/** - * Return code: A QoS value that falls outside of the acceptable range (0,1,2) - */ -#define MQTTCLIENT_BAD_QOS -9 -/** - * Return code: Attempting SSL connection using non-SSL version of library - */ -#define MQTTCLIENT_SSL_NOT_SUPPORTED -10 - /** - * Return code: unrecognized MQTT version - */ - #define MQTTCLIENT_BAD_MQTT_VERSION -11 -/** - * Return code: protocol prefix in serverURI should be: - * @li @em tcp:// or @em mqtt:// - Insecure TCP - * @li @em ssl:// or @em mqtts:// - Encrypted SSL/TLS - * @li @em ws:// - Insecure websockets - * @li @em wss:// - Secure web sockets - * The TLS enabled prefixes (ssl, mqtts, wss) are only valid if a TLS - * version of the library is linked with. - */ -#define MQTTCLIENT_BAD_PROTOCOL -14 - /** - * Return code: option not applicable to the requested version of MQTT - */ - #define MQTTCLIENT_BAD_MQTT_OPTION -15 - /** - * Return code: call not applicable to the requested version of MQTT - */ - #define MQTTCLIENT_WRONG_MQTT_VERSION -16 - /** - * Return code: 0 length will topic on connect - */ - #define MQTTCLIENT_0_LEN_WILL_TOPIC -17 - - -/** - * Default MQTT version to connect with. Use 3.1.1 then fall back to 3.1 - */ -#define MQTTVERSION_DEFAULT 0 -/** - * MQTT version to connect with: 3.1 - */ -#define MQTTVERSION_3_1 3 -/** - * MQTT version to connect with: 3.1.1 - */ -#define MQTTVERSION_3_1_1 4 - /** - * MQTT version to connect with: 5 - */ - #define MQTTVERSION_5 5 -/** - * Bad return code from subscribe, as defined in the 3.1.1 specification - */ -#define MQTT_BAD_SUBSCRIBE 0x80 - -/** - * Initialization options - */ -typedef struct -{ - /** The eyecatcher for this structure. Must be MQTG. */ - char struct_id[4]; - /** The version number of this structure. Must be 0 */ - int struct_version; - /** 1 = we do openssl init, 0 = leave it to the application */ - int do_openssl_init; -} MQTTClient_init_options; - -#define MQTTClient_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 } - -/** - * Global init of mqtt library. Call once on program start to set global behaviour. - * do_openssl_init - if mqtt library should initialize OpenSSL (1) or rely on the caller to do it before using the library (0) - */ -LIBMQTT_API void MQTTClient_global_init(MQTTClient_init_options* inits); - -/** - * A handle representing an MQTT client. A valid client handle is available - * following a successful call to MQTTClient_create(). - */ -typedef void* MQTTClient; -/** - * A value representing an MQTT message. A delivery token is returned to the - * client application when a message is published. The token can then be used to - * check that the message was successfully delivered to its destination (see - * MQTTClient_publish(), - * MQTTClient_publishMessage(), - * MQTTClient_deliveryComplete(), - * MQTTClient_waitForCompletion() and - * MQTTClient_getPendingDeliveryTokens()). - */ -typedef int MQTTClient_deliveryToken; -typedef int MQTTClient_token; - -/** - * A structure representing the payload and attributes of an MQTT message. The - * message topic is not part of this structure (see MQTTClient_publishMessage(), - * MQTTClient_publish(), MQTTClient_receive(), MQTTClient_freeMessage() - * and MQTTClient_messageArrived()). - */ -typedef struct -{ - /** The eyecatcher for this structure. must be MQTM. */ - char struct_id[4]; - /** The version number of this structure. Must be 0 or 1 - * 0 indicates no message properties */ - int struct_version; - /** The length of the MQTT message payload in bytes. */ - int payloadlen; - /** A pointer to the payload of the MQTT message. */ - void* payload; - /** - * The quality of service (QoS) assigned to the message. - * There are three levels of QoS: - *
- *
QoS0
- *
Fire and forget - the message may not be delivered
- *
QoS1
- *
At least once - the message will be delivered, but may be - * delivered more than once in some circumstances.
- *
QoS2
- *
Once and one only - the message will be delivered exactly once.
- *
- */ - int qos; - /** - * The retained flag serves two purposes depending on whether the message - * it is associated with is being published or received. - * - * retained = true
- * For messages being published, a true setting indicates that the MQTT - * server should retain a copy of the message. The message will then be - * transmitted to new subscribers to a topic that matches the message topic. - * For subscribers registering a new subscription, the flag being true - * indicates that the received message is not a new one, but one that has - * been retained by the MQTT server. - * - * retained = false
- * For publishers, this indicates that this message should not be retained - * by the MQTT server. For subscribers, a false setting indicates this is - * a normal message, received as a result of it being published to the - * server. - */ - int retained; - /** - * The dup flag indicates whether or not this message is a duplicate. - * It is only meaningful when receiving QoS1 messages. When true, the - * client application should take appropriate action to deal with the - * duplicate message. - */ - int dup; - /** The message identifier is normally reserved for internal use by the - * MQTT client and server. - */ - int msgid; - /** - * The MQTT V5 properties associated with the message. - */ - MQTTProperties properties; -} MQTTClient_message; - -#define MQTTClient_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer } - -/** - * This is a callback function. The client application - * must provide an implementation of this function to enable asynchronous - * receipt of messages. The function is registered with the client library by - * passing it as an argument to MQTTClient_setCallbacks(). It is - * called by the client library when a new message that matches a client - * subscription has been received from the server. This function is executed on - * a separate thread to the one on which the client application is running. - * @param context A pointer to the context value originally passed to - * MQTTClient_setCallbacks(), which contains any application-specific context. - * @param topicName The topic associated with the received message. - * @param topicLen The length of the topic if there are one - * more NULL characters embedded in topicName, otherwise topicLen - * is 0. If topicLen is 0, the value returned by strlen(topicName) - * can be trusted. If topicLen is greater than 0, the full topic name - * can be retrieved by accessing topicName as a byte array of length - * topicLen. - * @param message The MQTTClient_message structure for the received message. - * This structure contains the message payload and attributes. - * @return This function must return 0 or 1 indicating whether or not - * the message has been safely received by the client application.
- * Returning 1 indicates that the message has been successfully handled. - * To free the message storage, ::MQTTClient_freeMessage must be called. - * To free the topic name storage, ::MQTTClient_free must be called.
- * Returning 0 indicates that there was a problem. In this - * case, the client library will reinvoke MQTTClient_messageArrived() to - * attempt to deliver the message to the application again. - * Do not free the message and topic storage when returning 0, otherwise - * the redelivery will fail. - */ -typedef int MQTTClient_messageArrived(void* context, char* topicName, int topicLen, MQTTClient_message* message); - -/** - * This is a callback function. The client application - * must provide an implementation of this function to enable asynchronous - * notification of delivery of messages. The function is registered with the - * client library by passing it as an argument to MQTTClient_setCallbacks(). - * It is called by the client library after the client application has - * published a message to the server. It indicates that the necessary - * handshaking and acknowledgements for the requested quality of service (see - * MQTTClient_message.qos) have been completed. This function is executed on a - * separate thread to the one on which the client application is running. - * Note:MQTTClient_deliveryComplete() is not called when messages are - * published at QoS0. - * @param context A pointer to the context value originally passed to - * MQTTClient_setCallbacks(), which contains any application-specific context. - * @param dt The ::MQTTClient_deliveryToken associated with - * the published message. Applications can check that all messages have been - * correctly published by matching the delivery tokens returned from calls to - * MQTTClient_publish() and MQTTClient_publishMessage() with the tokens passed - * to this callback. - */ -typedef void MQTTClient_deliveryComplete(void* context, MQTTClient_deliveryToken dt); - -/** - * This is a callback function. The client application - * must provide an implementation of this function to enable asynchronous - * notification of the loss of connection to the server. The function is - * registered with the client library by passing it as an argument to - * MQTTClient_setCallbacks(). It is called by the client library if the client - * loses its connection to the server. The client application must take - * appropriate action, such as trying to reconnect or reporting the problem. - * This function is executed on a separate thread to the one on which the - * client application is running. - * @param context A pointer to the context value originally passed to - * MQTTClient_setCallbacks(), which contains any application-specific context. - * @param cause The reason for the disconnection. - * Currently, cause is always set to NULL. - */ -typedef void MQTTClient_connectionLost(void* context, char* cause); - -/** - * This function sets the callback functions for a specific client. - * If your client application doesn't use a particular callback, set the - * relevant parameter to NULL. Calling MQTTClient_setCallbacks() puts the - * client into multi-threaded mode. Any necessary message acknowledgements and - * status communications are handled in the background without any intervention - * from the client application. See @ref async for more information. - * - * Note: The MQTT client must be disconnected when this function is - * called. - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param context A pointer to any application-specific context. The - * the context pointer is passed to each of the callback functions to - * provide access to the context information in the callback. - * @param cl A pointer to an MQTTClient_connectionLost() callback - * function. You can set this to NULL if your application doesn't handle - * disconnections. - * @param ma A pointer to an MQTTClient_messageArrived() callback - * function. This callback function must be set when you call - * MQTTClient_setCallbacks(), as otherwise there would be nowhere to deliver - * any incoming messages. - * @param dc A pointer to an MQTTClient_deliveryComplete() callback - * function. You can set this to NULL if your application publishes - * synchronously or if you do not want to check for successful delivery. - * @return ::MQTTCLIENT_SUCCESS if the callbacks were correctly set, - * ::MQTTCLIENT_FAILURE if an error occurred. - */ -LIBMQTT_API int MQTTClient_setCallbacks(MQTTClient handle, void* context, MQTTClient_connectionLost* cl, - MQTTClient_messageArrived* ma, MQTTClient_deliveryComplete* dc); - - -/** - * This is a callback function, which will be called when the a disconnect - * packet is received from the server. This applies to MQTT V5 and above only. - * @param context A pointer to the context value originally passed to - * ::MQTTClient_setDisconnected(), which contains any application-specific context. - * @param properties The MQTT V5 properties received with the disconnect, if any. - * @param reasonCode The MQTT V5 reason code received with the disconnect. - * Currently, cause is always set to NULL. - */ -typedef void MQTTClient_disconnected(void* context, MQTTProperties* properties, - enum MQTTReasonCodes reasonCode); - -/** - * Sets the MQTTClient_disconnected() callback function for a client. This will be called - * if a disconnect packet is received from the server. Only valid for MQTT V5 and above. - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param context A pointer to any application-specific context. The - * the context pointer is passed to each of the callback functions to - * provide access to the context information in the callback. - * @param co A pointer to an MQTTClient_disconnected() callback - * function. NULL removes the callback setting. - * @return ::MQTTCLIENT_SUCCESS if the callbacks were correctly set, - * ::MQTTCLIENT_FAILURE if an error occurred. - */ -LIBMQTT_API int MQTTClient_setDisconnected(MQTTClient handle, void* context, MQTTClient_disconnected* co); - -/** - * This is a callback function, the MQTT V5 version of MQTTClient_deliveryComplete(). - * The client application - * must provide an implementation of this function to enable asynchronous - * notification of the completed delivery of messages. - * It is called by the client library after the client application has - * published a message to the server. It indicates that the necessary - * handshaking and acknowledgements for the requested quality of service (see - * MQTTClient_message.qos) have been completed. This function is executed on a - * separate thread to the one on which the client application is running. - * Note: It is not called when messages are published at QoS0. - * @param context A pointer to the context value originally passed to - * MQTTClient_setCallbacks(), which contains any application-specific context. - * @param dt The ::MQTTClient_deliveryToken associated with - * the published message. Applications can check that all messages have been - * correctly published by matching the delivery tokens returned from calls to - * MQTTClient_publish() and MQTTClient_publishMessage() with the tokens passed - * to this callback. - * @param packet_type the last received packet type for this completion. For QoS 1 - * always PUBACK. For QoS 2 could be PUBREC or PUBCOMP. - * @param properties the MQTT V5 properties returned with the last packet from the server - * @param reasonCode the reason code returned from the server - */ -typedef void MQTTClient_published(void* context, int dt, int packet_type, MQTTProperties* properties, - enum MQTTReasonCodes reasonCode); - -LIBMQTT_API int MQTTClient_setPublished(MQTTClient handle, void* context, MQTTClient_published* co); - -/** - * This function creates an MQTT client ready for connection to the - * specified server and using the specified persistent storage (see - * MQTTClient_persistence). See also MQTTClient_destroy(). - * @param handle A pointer to an ::MQTTClient handle. The handle is - * populated with a valid client reference following a successful return from - * this function. - * @param serverURI A null-terminated string specifying the server to - * which the client will connect. It takes the form protocol://host:port. - * Currently, protocol must be: - *
- * @em tcp:// or @em mqtt:// - Insecure TCP - *
- * @em ssl:// or @em mqtts:// - Encrypted SSL/TLS - *
- * @em ws:// - Insecure websockets - *
- * @em wss:// - Secure web sockets - *
- * The TLS enabled prefixes (ssl, mqtts, wss) are only valid if a TLS - * version of the library is linked with. - * For host, you can specify either an IP address or a host name. For - * instance, to connect to a server running on the local machines with the - * default MQTT port, specify tcp://localhost:1883. - * @param clientId The client identifier passed to the server when the - * client connects to it. It is a null-terminated UTF-8 encoded string. - * @param persistence_type The type of persistence to be used by the client: - *
- * ::MQTTCLIENT_PERSISTENCE_NONE: Use in-memory persistence. If the device or - * system on which the client is running fails or is switched off, the current - * state of any in-flight messages is lost and some messages may not be - * delivered even at QoS1 and QoS2. - *
- * ::MQTTCLIENT_PERSISTENCE_DEFAULT: Use the default (file system-based) - * persistence mechanism. Status about in-flight messages is held in persistent - * storage and provides some protection against message loss in the case of - * unexpected failure. - *
- * ::MQTTCLIENT_PERSISTENCE_USER: Use an application-specific persistence - * implementation. Using this type of persistence gives control of the - * persistence mechanism to the application. The application has to implement - * the MQTTClient_persistence interface. - * @param persistence_context If the application uses - * ::MQTTCLIENT_PERSISTENCE_NONE persistence, this argument is unused and should - * be set to NULL. For ::MQTTCLIENT_PERSISTENCE_DEFAULT persistence, it - * should be set to the location of the persistence directory (if set - * to NULL, the persistence directory used is the working directory). - * Applications that use ::MQTTCLIENT_PERSISTENCE_USER persistence set this - * argument to point to a valid MQTTClient_persistence structure. - * @return ::MQTTCLIENT_SUCCESS if the client is successfully created, otherwise - * an error code is returned. - */ -LIBMQTT_API int MQTTClient_create(MQTTClient* handle, const char* serverURI, const char* clientId, - int persistence_type, void* persistence_context); - -/** Options for the ::MQTTClient_createWithOptions call */ -typedef struct -{ - /** The eyecatcher for this structure. must be MQCO. */ - char struct_id[4]; - /** The version number of this structure. Must be 0 */ - int struct_version; - /** Whether the MQTT version is 3.1, 3.1.1, or 5. To use V5, this must be set. - * MQTT V5 has to be chosen here, because during the create call the message persistence - * is initialized, and we want to know whether the format of any persisted messages - * is appropriate for the MQTT version we are going to connect with. Selecting 3.1 or - * 3.1.1 and attempting to read 5.0 persisted messages will result in an error on create. */ - int MQTTVersion; -} MQTTClient_createOptions; - -#define MQTTClient_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 0, MQTTVERSION_DEFAULT } - -/** - * A version of :MQTTClient_create() with additional options. - * This function creates an MQTT client ready for connection to the - * specified server and using the specified persistent storage (see - * MQTTClient_persistence). See also MQTTClient_destroy(). - * @param handle A pointer to an ::MQTTClient handle. The handle is - * populated with a valid client reference following a successful return from - * this function. - * @param serverURI A null-terminated string specifying the server to - * which the client will connect. It takes the form protocol://host:port. - * Currently, protocol must be tcp or ssl. - * For host, you can - * specify either an IP address or a host name. For instance, to connect to - * a server running on the local machines with the default MQTT port, specify - * tcp://localhost:1883. - * @param clientId The client identifier passed to the server when the - * client connects to it. It is a null-terminated UTF-8 encoded string. - * @param persistence_type The type of persistence to be used by the client: - *
- * ::MQTTCLIENT_PERSISTENCE_NONE: Use in-memory persistence. If the device or - * system on which the client is running fails or is switched off, the current - * state of any in-flight messages is lost and some messages may not be - * delivered even at QoS1 and QoS2. - *
- * ::MQTTCLIENT_PERSISTENCE_DEFAULT: Use the default (file system-based) - * persistence mechanism. Status about in-flight messages is held in persistent - * storage and provides some protection against message loss in the case of - * unexpected failure. - *
- * ::MQTTCLIENT_PERSISTENCE_USER: Use an application-specific persistence - * implementation. Using this type of persistence gives control of the - * persistence mechanism to the application. The application has to implement - * the MQTTClient_persistence interface. - * @param persistence_context If the application uses - * ::MQTTCLIENT_PERSISTENCE_NONE persistence, this argument is unused and should - * be set to NULL. For ::MQTTCLIENT_PERSISTENCE_DEFAULT persistence, it - * should be set to the location of the persistence directory (if set - * to NULL, the persistence directory used is the working directory). - * Applications that use ::MQTTCLIENT_PERSISTENCE_USER persistence set this - * argument to point to a valid MQTTClient_persistence structure. - * @param options additional options for the create. - * @return ::MQTTCLIENT_SUCCESS if the client is successfully created, otherwise - * an error code is returned. - */ -LIBMQTT_API int MQTTClient_createWithOptions(MQTTClient* handle, const char* serverURI, const char* clientId, - int persistence_type, void* persistence_context, MQTTClient_createOptions* options); - -/** - * MQTTClient_willOptions defines the MQTT "Last Will and Testament" (LWT) settings for - * the client. In the event that a client unexpectedly loses its connection to - * the server, the server publishes the LWT message to the LWT topic on - * behalf of the client. This allows other clients (subscribed to the LWT topic) - * to be made aware that the client has disconnected. To enable the LWT - * function for a specific client, a valid pointer to an MQTTClient_willOptions - * structure is passed in the MQTTClient_connectOptions structure used in the - * MQTTClient_connect() call that connects the client to the server. The pointer - * to MQTTClient_willOptions can be set to NULL if the LWT function is not - * required. - */ -typedef struct -{ - /** The eyecatcher for this structure. must be MQTW. */ - char struct_id[4]; - /** The version number of this structure. Must be 0 or 1 - 0 means there is no binary payload option - */ - int struct_version; - /** The LWT topic to which the LWT message will be published. */ - const char* topicName; - /** The LWT payload in string form. */ - const char* message; - /** - * The retained flag for the LWT message (see MQTTClient_message.retained). - */ - int retained; - /** - * The quality of service setting for the LWT message (see - * MQTTClient_message.qos and @ref qos). - */ - int qos; - /** The LWT payload in binary form. This is only checked and used if the message option is NULL */ - struct - { - int len; /**< binary payload length */ - const void* data; /**< binary payload data */ - } payload; -} MQTTClient_willOptions; - -#define MQTTClient_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, {0, NULL} } - -#define MQTT_SSL_VERSION_DEFAULT 0 -#define MQTT_SSL_VERSION_TLS_1_0 1 -#define MQTT_SSL_VERSION_TLS_1_1 2 -#define MQTT_SSL_VERSION_TLS_1_2 3 - -/** -* MQTTClient_sslProperties defines the settings to establish an SSL/TLS connection using the -* OpenSSL library. It covers the following scenarios: -* - Server authentication: The client needs the digital certificate of the server. It is included -* in a store containting trusted material (also known as "trust store"). -* - Mutual authentication: Both client and server are authenticated during the SSL handshake. In -* addition to the digital certificate of the server in a trust store, the client will need its own -* digital certificate and the private key used to sign its digital certificate stored in a "key store". -* - Anonymous connection: Both client and server do not get authenticated and no credentials are needed -* to establish an SSL connection. Note that this scenario is not fully secure since it is subject to -* man-in-the-middle attacks. -*/ -typedef struct -{ - /** The eyecatcher for this structure. Must be MQTS */ - char struct_id[4]; - - /** The version number of this structure. Must be 0, 1, 2, 3, 4 or 5. - * 0 means no sslVersion - * 1 means no verify, CApath - * 2 means no ssl_error_context, ssl_error_cb - * 3 means no ssl_psk_cb, ssl_psk_context, disableDefaultTrustStore - * 4 means no protos, protos_len - */ - int struct_version; - - /** The file in PEM format containing the public digital certificates trusted by the client. */ - const char* trustStore; - - /** The file in PEM format containing the public certificate chain of the client. It may also include - * the client's private key. - */ - const char* keyStore; - - /** If not included in the sslKeyStore, this setting points to the file in PEM format containing - * the client's private key. - */ - const char* privateKey; - - /** The password to load the client's privateKey if encrypted. */ - const char* privateKeyPassword; - - /** - * The list of cipher suites that the client will present to the server during the SSL handshake. For a - * full explanation of the cipher list format, please see the OpenSSL on-line documentation: - * http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT - * If this setting is ommitted, its default value will be "ALL", that is, all the cipher suites -excluding - * those offering no encryption- will be considered. - * This setting can be used to set an SSL anonymous connection ("aNULL" string value, for instance). - */ - const char* enabledCipherSuites; - - /** True/False option to enable verification of the server certificate **/ - int enableServerCertAuth; - - /** The SSL/TLS version to use. Specify one of MQTT_SSL_VERSION_DEFAULT (0), - * MQTT_SSL_VERSION_TLS_1_0 (1), MQTT_SSL_VERSION_TLS_1_1 (2) or MQTT_SSL_VERSION_TLS_1_2 (3). - * Only used if struct_version is >= 1. - */ - int sslVersion; - - /** - * Whether to carry out post-connect checks, including that a certificate - * matches the given host name. - * Exists only if struct_version >= 2 - */ - int verify; - - /** - * From the OpenSSL documentation: - * If CApath is not NULL, it points to a directory containing CA certificates in PEM format. - * Exists only if struct_version >= 2 - */ - const char* CApath; - - /** - * Callback function for OpenSSL error handler ERR_print_errors_cb - * Exists only if struct_version >= 3 - */ - int (*ssl_error_cb) (const char *str, size_t len, void *u); - - /** - * Application-specific contex for OpenSSL error handler ERR_print_errors_cb - * Exists only if struct_version >= 3 - */ - void* ssl_error_context; - - /** - * Callback function for setting TLS-PSK options. Parameters correspond to that of - * SSL_CTX_set_psk_client_callback, except for u which is the pointer ssl_psk_context. - * Exists only if struct_version >= 4 - */ - unsigned int (*ssl_psk_cb) (const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len, void *u); - - /** - * Application-specific contex for ssl_psk_cb - * Exists only if struct_version >= 4 - */ - void* ssl_psk_context; - - /** - * Don't load default SSL CA. Should be used together with PSK to make sure - * regular servers with certificate in place is not accepted. - * Exists only if struct_version >= 4 - */ - int disableDefaultTrustStore; - - /** - * The protocol-lists must be in wire-format, which is defined as a vector of non-empty, 8-bit length-prefixed, byte strings. - * The length-prefix byte is not included in the length. Each string is limited to 255 bytes. A byte-string length of 0 is invalid. - * A truncated byte-string is invalid. - * Check documentation for SSL_CTX_set_alpn_protos - * Exists only if struct_version >= 5 - */ - const unsigned char *protos; - - /** - * The length of the vector protos vector - * Exists only if struct_version >= 5 - */ - unsigned int protos_len; -} MQTTClient_SSLOptions; - -#define MQTTClient_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 5, NULL, NULL, NULL, NULL, NULL, 1, MQTT_SSL_VERSION_DEFAULT, 0, NULL, NULL, NULL, NULL, NULL, 0, NULL, 0 } - -/** - * MQTTClient_libraryInfo is used to store details relating to the currently used - * library such as the version in use, the time it was built and relevant openSSL - * options. - * There is one static instance of this struct in MQTTClient.c - */ - -typedef struct -{ - const char* name; - const char* value; -} MQTTClient_nameValue; - -/** - * This function returns version information about the library. - * no trace information will be returned. - * @return an array of strings describing the library. The last entry is a NULL pointer. - */ -LIBMQTT_API MQTTClient_nameValue* MQTTClient_getVersionInfo(void); - -/** - * MQTTClient_connectOptions defines several settings that control the way the - * client connects to an MQTT server. - * - * Note: Default values are not defined for members of - * MQTTClient_connectOptions so it is good practice to specify all settings. - * If the MQTTClient_connectOptions structure is defined as an automatic - * variable, all members are set to random values and thus must be set by the - * client application. If the MQTTClient_connectOptions structure is defined - * as a static variable, initialization (in compliant compilers) sets all - * values to 0 (NULL for pointers). A #keepAliveInterval setting of 0 prevents - * correct operation of the client and so you must at least set a value - * for #keepAliveInterval. - * - * Suitable default values are set in the following initializers: - * - MQTTClient_connectOptions_initializer: for MQTT 3.1.1 non-WebSockets - * - MQTTClient_connectOptions_initializer5: for MQTT 5.0 non-WebSockets - * - MQTTClient_connectOptions_initializer_ws: for MQTT 3.1.1 WebSockets - * - MQTTClient_connectOptions_initializer5_ws: for MQTT 5.0 WebSockets - */ -typedef struct -{ - /** The eyecatcher for this structure. must be MQTC. */ - char struct_id[4]; - /** The version number of this structure. Must be 0, 1, 2, 3, 4, 5, 6, 7 or 8. - * 0 signifies no SSL options and no serverURIs - * 1 signifies no serverURIs - * 2 signifies no MQTTVersion - * 3 signifies no returned values - * 4 signifies no binary password option - * 5 signifies no maxInflightMessages and cleanstart - * 6 signifies no HTTP headers option - * 7 signifies no HTTP proxy and HTTPS proxy options - */ - int struct_version; - /** The "keep alive" interval, measured in seconds, defines the maximum time - * that should pass without communication between the client and the server - * The client will ensure that at least one message travels across the - * network within each keep alive period. In the absence of a data-related - * message during the time period, the client sends a very small MQTT - * "ping" message, which the server will acknowledge. The keep alive - * interval enables the client to detect when the server is no longer - * available without having to wait for the long TCP/IP timeout. - */ - int keepAliveInterval; - /** - * This is a boolean value. The cleansession setting controls the behaviour - * of both the client and the server at connection and disconnection time. - * The client and server both maintain session state information. This - * information is used to ensure "at least once" and "exactly once" - * delivery, and "exactly once" receipt of messages. Session state also - * includes subscriptions created by an MQTT client. You can choose to - * maintain or discard state information between sessions. - * - * When cleansession is true, the state information is discarded at - * connect and disconnect. Setting cleansession to false keeps the state - * information. When you connect an MQTT client application with - * MQTTClient_connect(), the client identifies the connection using the - * client identifier and the address of the server. The server checks - * whether session information for this client - * has been saved from a previous connection to the server. If a previous - * session still exists, and cleansession=true, then the previous session - * information at the client and server is cleared. If cleansession=false, - * the previous session is resumed. If no previous session exists, a new - * session is started. - */ - int cleansession; - /** - * This is a boolean value that controls how many messages can be in-flight - * simultaneously. Setting reliable to true means that a published - * message must be completed (acknowledgements received) before another - * can be sent. Attempts to publish additional messages receive an - * ::MQTTCLIENT_MAX_MESSAGES_INFLIGHT return code. Setting this flag to - * false allows up to 10 messages to be in-flight. This can increase - * overall throughput in some circumstances. - */ - int reliable; - /** - * This is a pointer to an MQTTClient_willOptions structure. If your - * application does not make use of the Last Will and Testament feature, - * set this pointer to NULL. - */ - MQTTClient_willOptions* will; - /** - * MQTT servers that support the MQTT v3.1.1 protocol provide authentication - * and authorisation by user name and password. This is the user name - * parameter. - */ - const char* username; - /** - * MQTT servers that support the MQTT v3.1.1 protocol provide authentication - * and authorisation by user name and password. This is the password - * parameter. - */ - const char* password; - /** - * The time interval in seconds to allow a connect to complete. - */ - int connectTimeout; - /** - * The time interval in seconds after which unacknowledged publish requests are - * retried during a TCP session. With MQTT 3.1.1 and later, retries are - * not required except on reconnect. 0 turns off in-session retries, and is the - * recommended setting. Adding retries to an already overloaded network only - * exacerbates the problem. - */ - int retryInterval; - /** - * This is a pointer to an MQTTClient_SSLOptions structure. If your - * application does not make use of SSL, set this pointer to NULL. - */ - MQTTClient_SSLOptions* ssl; - /** - * The number of entries in the optional serverURIs array. Defaults to 0. - */ - int serverURIcount; - /** - * An optional array of null-terminated strings specifying the servers to - * which the client will connect. Each string takes the form protocol://host:port. - * protocol must be tcp, ssl, ws or wss. - * The TLS enabled prefixes (ssl, wss) are only valid if a TLS version of the library - * is linked with. - * For host, you can - * specify either an IP address or a host name. For instance, to connect to - * a server running on the local machines with the default MQTT port, specify - * tcp://localhost:1883. - * If this list is empty (the default), the server URI specified on MQTTClient_create() - * is used. - */ - char* const* serverURIs; - /** - * Sets the version of MQTT to be used on the connect. - * MQTTVERSION_DEFAULT (0) = default: start with 3.1.1, and if that fails, fall back to 3.1 - * MQTTVERSION_3_1 (3) = only try version 3.1 - * MQTTVERSION_3_1_1 (4) = only try version 3.1.1 - * MQTTVERSION_5 (5) = only try version 5.0 - */ - int MQTTVersion; - /** - * Returned from the connect when the MQTT version used to connect is 3.1.1 - */ - struct - { - const char* serverURI; /**< the serverURI connected to */ - int MQTTVersion; /**< the MQTT version used to connect with */ - int sessionPresent; /**< if the MQTT version is 3.1.1, the value of sessionPresent returned in the connack */ - } returned; - /** - * Optional binary password. Only checked and used if the password option is NULL - */ - struct - { - int len; /**< binary password length */ - const void* data; /**< binary password data */ - } binarypwd; - /** - * The maximum number of messages in flight - */ - int maxInflightMessages; - /* - * MQTT V5 clean start flag. Only clears state at the beginning of the session. - */ - int cleanstart; - /** - * HTTP headers for websockets - */ - const MQTTClient_nameValue* httpHeaders; - /** - * HTTP proxy - */ - const char* httpProxy; - /** - * HTTPS proxy - */ - const char* httpsProxy; -} MQTTClient_connectOptions; - -/** Initializer for connect options for MQTT 3.1.1 non-WebSocket connections */ -#define MQTTClient_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 8, 60, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\ -0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL} - -/** Initializer for connect options for MQTT 5.0 non-WebSocket connections */ -#define MQTTClient_connectOptions_initializer5 { {'M', 'Q', 'T', 'C'}, 8, 60, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\ -0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL} - -/** Initializer for connect options for MQTT 3.1.1 WebSockets connections. - * The keepalive interval is set to 45 seconds to avoid webserver 60 second inactivity timeouts. - */ -#define MQTTClient_connectOptions_initializer_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\ -0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL} - -/** Initializer for connect options for MQTT 5.0 WebSockets connections. - * The keepalive interval is set to 45 seconds to avoid webserver 60 second inactivity timeouts. - */ -#define MQTTClient_connectOptions_initializer5_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\ -0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL} - -/** - * This function attempts to connect a previously-created client (see - * MQTTClient_create()) to an MQTT server using the specified options. If you - * want to enable asynchronous message and status notifications, you must call - * MQTTClient_setCallbacks() prior to MQTTClient_connect(). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param options A pointer to a valid MQTTClient_connectOptions - * structure. - * @return ::MQTTCLIENT_SUCCESS if the client successfully connects to the - * server. An error code is returned if the client was unable to connect to - * the server. - * Error codes greater than 0 are returned by the MQTT protocol:

- * 1: Connection refused: Unacceptable protocol version
- * 2: Connection refused: Identifier rejected
- * 3: Connection refused: Server unavailable
- * 4: Connection refused: Bad user name or password
- * 5: Connection refused: Not authorized
- * 6-255: Reserved for future use
- */ -LIBMQTT_API int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions* options); - -/** MQTT version 5.0 response information */ -typedef struct MQTTResponse -{ - int version; /* the version number of this structure */ - enum MQTTReasonCodes reasonCode; /* the MQTT 5.0 reason code returned */ - int reasonCodeCount; /* the number of reason codes. Used for subscribeMany5 and unsubscribeMany5 */ - enum MQTTReasonCodes* reasonCodes; /* a list of reason codes. Used for subscribeMany5 and unsubscribeMany5 */ - MQTTProperties* properties; /* optionally, the MQTT 5.0 properties returned */ -} MQTTResponse; - -#define MQTTResponse_initializer {1, MQTTREASONCODE_SUCCESS, 0, NULL, NULL} - -/** - * Frees the storage associated with the MQTT response. - * @param response the response structure to be freed - */ -LIBMQTT_API void MQTTResponse_free(MQTTResponse response); - -/** - * Attempts to connect a previously-created client (see - * MQTTClient_create()) to an MQTT server using MQTT version 5.0 and the specified options. If you - * want to enable asynchronous message and status notifications, you must call - * MQTTClient_setCallbacks() prior to MQTTClient_connect(). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param options A pointer to a valid MQTTClient_connectOptions - * structure. - * @param connectProperties the MQTT 5.0 connect properties to use - * @param willProperties the MQTT 5.0 properties to set on the will message - * @return the MQTT 5.0 response information: error codes and properties. - */ -LIBMQTT_API MQTTResponse MQTTClient_connect5(MQTTClient handle, MQTTClient_connectOptions* options, - MQTTProperties* connectProperties, MQTTProperties* willProperties); - -/** - * This function attempts to disconnect the client from the MQTT - * server. In order to allow the client time to complete handling of messages - * that are in-flight when this function is called, a timeout period is - * specified. When the timeout period has expired, the client disconnects even - * if there are still outstanding message acknowledgements. - * The next time the client connects to the same server, any QoS 1 or 2 - * messages which have not completed will be retried depending on the - * cleansession settings for both the previous and the new connection (see - * MQTTClient_connectOptions.cleansession and MQTTClient_connect()). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param timeout The client delays disconnection for up to this time (in - * milliseconds) in order to allow in-flight message transfers to complete. - * @return ::MQTTCLIENT_SUCCESS if the client successfully disconnects from - * the server. An error code is returned if the client was unable to disconnect - * from the server - */ -LIBMQTT_API int MQTTClient_disconnect(MQTTClient handle, int timeout); - -LIBMQTT_API int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties* props); - -/** - * This function allows the client application to test whether or not a - * client is currently connected to the MQTT server. - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @return Boolean true if the client is connected, otherwise false. - */ -LIBMQTT_API int MQTTClient_isConnected(MQTTClient handle); - - -/* Subscribe is synchronous. QoS list parameter is changed on return to granted QoSs. - Returns return code, MQTTCLIENT_SUCCESS == success, non-zero some sort of error (TBD) */ - -/** - * This function attempts to subscribe a client to a single topic, which may - * contain wildcards (see @ref wildcard). This call also specifies the - * @ref qos requested for the subscription - * (see also MQTTClient_subscribeMany()). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param topic The subscription topic, which may include wildcards. - * @param qos The requested quality of service for the subscription. - * @return ::MQTTCLIENT_SUCCESS if the subscription request is successful. - * An error code is returned if there was a problem registering the - * subscription. - */ -LIBMQTT_API int MQTTClient_subscribe(MQTTClient handle, const char* topic, int qos); - -/** - * This function attempts to subscribe an MQTT version 5.0 client to a single topic, which may - * contain wildcards (see @ref wildcard). This call also specifies the - * @ref qos requested for the subscription - * (see also MQTTClient_subscribeMany()). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param topic The subscription topic, which may include wildcards. - * @param qos The requested quality of service for the subscription. - * @param opts the MQTT 5.0 subscribe options to be used - * @param props the MQTT 5.0 properties to be used - * @return the MQTT 5.0 response information: error codes and properties. - */ -LIBMQTT_API MQTTResponse MQTTClient_subscribe5(MQTTClient handle, const char* topic, int qos, - MQTTSubscribe_options* opts, MQTTProperties* props); - -/** - * This function attempts to subscribe a client to a list of topics, which may - * contain wildcards (see @ref wildcard). This call also specifies the - * @ref qos requested for each topic (see also MQTTClient_subscribe()). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param count The number of topics for which the client is requesting - * subscriptions. - * @param topic An array (of length count) of pointers to - * topics, each of which may include wildcards. - * @param qos An array (of length count) of @ref qos - * values. qos[n] is the requested QoS for topic[n]. - * @return ::MQTTCLIENT_SUCCESS if the subscription request is successful. - * An error code is returned if there was a problem registering the - * subscriptions. - */ -LIBMQTT_API int MQTTClient_subscribeMany(MQTTClient handle, int count, char* const* topic, int* qos); - -/** - * This function attempts to subscribe an MQTT version 5.0 client to a list of topics, which may - * contain wildcards (see @ref wildcard). This call also specifies the - * @ref qos requested for each topic (see also MQTTClient_subscribe()). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param count The number of topics for which the client is requesting - * subscriptions. - * @param topic An array (of length count) of pointers to - * topics, each of which may include wildcards. - * @param qos An array (of length count) of @ref qos - * values. qos[n] is the requested QoS for topic[n]. - * @param opts the MQTT 5.0 subscribe options to be used - * @param props the MQTT 5.0 properties to be used - * @return the MQTT 5.0 response information: error codes and properties. - */ -LIBMQTT_API MQTTResponse MQTTClient_subscribeMany5(MQTTClient handle, int count, char* const* topic, - int* qos, MQTTSubscribe_options* opts, MQTTProperties* props); - -/** - * This function attempts to remove an existing subscription made by the - * specified client. - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param topic The topic for the subscription to be removed, which may - * include wildcards (see @ref wildcard). - * @return ::MQTTCLIENT_SUCCESS if the subscription is removed. - * An error code is returned if there was a problem removing the - * subscription. - */ -LIBMQTT_API int MQTTClient_unsubscribe(MQTTClient handle, const char* topic); - -/** - * This function attempts to remove an existing subscription made by the - * specified client using MQTT 5.0. - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param topic The topic for the subscription to be removed, which may - * include wildcards (see @ref wildcard). - * @param props the MQTT 5.0 properties to be used - * @return the MQTT 5.0 response information: error codes and properties. - */ -LIBMQTT_API MQTTResponse MQTTClient_unsubscribe5(MQTTClient handle, const char* topic, MQTTProperties* props); - -/** - * This function attempts to remove existing subscriptions to a list of topics - * made by the specified client. - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param count The number subscriptions to be removed. - * @param topic An array (of length count) of pointers to the topics of - * the subscriptions to be removed, each of which may include wildcards. - * @return ::MQTTCLIENT_SUCCESS if the subscriptions are removed. - * An error code is returned if there was a problem removing the subscriptions. - */ -LIBMQTT_API int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char* const* topic); - -/** - * This function attempts to remove existing subscriptions to a list of topics - * made by the specified client using MQTT version 5.0. - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param count The number subscriptions to be removed. - * @param topic An array (of length count) of pointers to the topics of - * the subscriptions to be removed, each of which may include wildcards. - * @param props the MQTT 5.0 properties to be used - * @return the MQTT 5.0 response information: error codes and properties. - */ -LIBMQTT_API MQTTResponse MQTTClient_unsubscribeMany5(MQTTClient handle, int count, char* const* topic, MQTTProperties* props); - -/** - * This function attempts to publish a message to a given topic (see also - * MQTTClient_publishMessage()). An ::MQTTClient_deliveryToken is issued when - * this function returns successfully. If the client application needs to - * test for succesful delivery of QoS1 and QoS2 messages, this can be done - * either asynchronously or synchronously (see @ref async, - * ::MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param topicName The topic associated with this message. - * @param payloadlen The length of the payload in bytes. - * @param payload A pointer to the byte array payload of the message. - * @param qos The @ref qos of the message. - * @param retained The retained flag for the message. - * @param dt A pointer to an ::MQTTClient_deliveryToken. This is populated - * with a token representing the message when the function returns - * successfully. If your application does not use delivery tokens, set this - * argument to NULL. - * @return ::MQTTCLIENT_SUCCESS if the message is accepted for publication. - * An error code is returned if there was a problem accepting the message. - */ -LIBMQTT_API int MQTTClient_publish(MQTTClient handle, const char* topicName, int payloadlen, const void* payload, int qos, int retained, - MQTTClient_deliveryToken* dt); - -/** - * Attempts to publish a message to a given topic using MQTT version 5.0 (see also - * MQTTClient_publishMessage5()). An ::MQTTClient_deliveryToken is issued when - * this function returns successfully. If the client application needs to - * test for succesful delivery of QoS1 and QoS2 messages, this can be done - * either asynchronously or synchronously (see @ref async, - * ::MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param topicName The topic associated with this message. - * @param payloadlen The length of the payload in bytes. - * @param payload A pointer to the byte array payload of the message. - * @param qos The @ref qos of the message. - * @param retained The retained flag for the message. - * @param properties the MQTT 5.0 properties to be used - * @param dt A pointer to an ::MQTTClient_deliveryToken. This is populated - * with a token representing the message when the function returns - * successfully. If your application does not use delivery tokens, set this - * argument to NULL. - * @return the MQTT 5.0 response information: error codes and properties. - */ -LIBMQTT_API MQTTResponse MQTTClient_publish5(MQTTClient handle, const char* topicName, int payloadlen, const void* payload, - int qos, int retained, MQTTProperties* properties, MQTTClient_deliveryToken* dt); -/** - * This function attempts to publish a message to a given topic (see also - * MQTTClient_publish()). An ::MQTTClient_deliveryToken is issued when - * this function returns successfully. If the client application needs to - * test for succesful delivery of QoS1 and QoS2 messages, this can be done - * either asynchronously or synchronously (see @ref async, - * ::MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param topicName The topic associated with this message. - * @param msg A pointer to a valid MQTTClient_message structure containing - * the payload and attributes of the message to be published. - * @param dt A pointer to an ::MQTTClient_deliveryToken. This is populated - * with a token representing the message when the function returns - * successfully. If your application does not use delivery tokens, set this - * argument to NULL. - * @return ::MQTTCLIENT_SUCCESS if the message is accepted for publication. - * An error code is returned if there was a problem accepting the message. - */ -LIBMQTT_API int MQTTClient_publishMessage(MQTTClient handle, const char* topicName, MQTTClient_message* msg, MQTTClient_deliveryToken* dt); - - -/** - * Attempts to publish a message to the given topic using MQTT version 5.0 - * (see also - * MQTTClient_publish5()). An ::MQTTClient_deliveryToken is issued when - * this function returns successfully. If the client application needs to - * test for succesful delivery of QoS1 and QoS2 messages, this can be done - * either asynchronously or synchronously (see @ref async, - * ::MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param topicName The topic associated with this message. - * @param msg A pointer to a valid MQTTClient_message structure containing - * the payload and attributes of the message to be published. - * @param dt A pointer to an ::MQTTClient_deliveryToken. This is populated - * with a token representing the message when the function returns - * successfully. If your application does not use delivery tokens, set this - * argument to NULL. - * @return the MQTT 5.0 response information: error codes and properties. - */ -LIBMQTT_API MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char* topicName, MQTTClient_message* msg, - MQTTClient_deliveryToken* dt); - -/** - * This function is called by the client application to synchronize execution - * of the main thread with completed publication of a message. When called, - * MQTTClient_waitForCompletion() blocks execution until the message has been - * successful delivered or the specified timeout has expired. See @ref async. - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param dt The ::MQTTClient_deliveryToken that represents the message being - * tested for successful delivery. Delivery tokens are issued by the - * publishing functions MQTTClient_publish() and MQTTClient_publishMessage(). - * @param timeout The maximum time to wait in milliseconds. - * @return ::MQTTCLIENT_SUCCESS if the message was successfully delivered. - * An error code is returned if the timeout expires or there was a problem - * checking the token. - */ -LIBMQTT_API int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout); - - -/** - * This function sets a pointer to an array of delivery tokens for - * messages that are currently in-flight (pending completion). - * - * Important note: The memory used to hold the array of tokens is - * malloc()'d in this function. The client application is responsible for - * freeing this memory when it is no longer required. - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param tokens The address of a pointer to an ::MQTTClient_deliveryToken. - * When the function returns successfully, the pointer is set to point to an - * array of tokens representing messages pending completion. The last member of - * the array is set to -1 to indicate there are no more tokens. If no tokens - * are pending, the pointer is set to NULL. - * @return ::MQTTCLIENT_SUCCESS if the function returns successfully. - * An error code is returned if there was a problem obtaining the list of - * pending tokens. - */ -LIBMQTT_API int MQTTClient_getPendingDeliveryTokens(MQTTClient handle, MQTTClient_deliveryToken **tokens); - -/** - * When implementing a single-threaded client, call this function periodically - * to allow processing of message retries and to send MQTT keepalive pings. - * If the application is calling MQTTClient_receive() regularly, then it is - * not necessary to call this function. - */ -LIBMQTT_API void MQTTClient_yield(void); - -/** - * This function performs a synchronous receive of incoming messages. It should - * be used only when the client application has not set callback methods to - * support asynchronous receipt of messages (see @ref async and - * MQTTClient_setCallbacks()). Using this function allows a single-threaded - * client subscriber application to be written. When called, this function - * blocks until the next message arrives or the specified timeout expires - *(see also MQTTClient_yield()). - * - * Important note: The application must free() the memory allocated - * to the topic and the message when processing is complete (see - * MQTTClient_freeMessage()). - * @param handle A valid client handle from a successful call to - * MQTTClient_create(). - * @param topicName The address of a pointer to a topic. This function - * allocates the memory for the topic and returns it to the application - * by setting topicName to point to the topic. - * @param topicLen The length of the topic. If the return code from this - * function is ::MQTTCLIENT_TOPICNAME_TRUNCATED, the topic contains embedded - * NULL characters and the full topic should be retrieved by using - * topicLen. - * @param message The address of a pointer to the received message. This - * function allocates the memory for the message and returns it to the - * application by setting message to point to the received message. - * The pointer is set to NULL if the timeout expires. - * @param timeout The length of time to wait for a message in milliseconds. - * @return ::MQTTCLIENT_SUCCESS or ::MQTTCLIENT_TOPICNAME_TRUNCATED if a - * message is received. ::MQTTCLIENT_SUCCESS can also indicate that the - * timeout expired, in which case message is NULL. An error code is - * returned if there was a problem trying to receive a message. - */ -LIBMQTT_API int MQTTClient_receive(MQTTClient handle, char** topicName, int* topicLen, MQTTClient_message** message, - unsigned long timeout); - -/** - * This function frees memory allocated to an MQTT message, including the - * additional memory allocated to the message payload. The client application - * calls this function when the message has been fully processed. Important - * note: This function does not free the memory allocated to a message - * topic string. It is the responsibility of the client application to free - * this memory using the MQTTClient_free() library function. - * @param msg The address of a pointer to the ::MQTTClient_message structure - * to be freed. - */ -LIBMQTT_API void MQTTClient_freeMessage(MQTTClient_message** msg); - -/** - * This function frees memory allocated by the MQTT C client library, especially the - * topic name. This is needed on Windows when the client libary and application - * program have been compiled with different versions of the C compiler. It is - * thus good policy to always use this function when freeing any MQTT C client- - * allocated memory. - * @param ptr The pointer to the client library storage to be freed. - */ -LIBMQTT_API void MQTTClient_free(void* ptr); - -/** - * This function is used to allocate memory to be used or freed by the MQTT C client library, - * especially the data in user persistence. This is needed on Windows when the client library - * and application program have been compiled with different versions of the C compiler. - * @param size The size of the memory to be allocated. - */ -LIBMQTT_API void* MQTTClient_malloc(size_t size); - -/** - * This function frees the memory allocated to an MQTT client (see - * MQTTClient_create()). It should be called when the client is no longer - * required. - * @param handle A pointer to the handle referring to the ::MQTTClient - * structure to be freed. - */ -LIBMQTT_API void MQTTClient_destroy(MQTTClient* handle); - - -enum MQTTCLIENT_TRACE_LEVELS -{ - MQTTCLIENT_TRACE_MAXIMUM = 1, - MQTTCLIENT_TRACE_MEDIUM, - MQTTCLIENT_TRACE_MINIMUM, - MQTTCLIENT_TRACE_PROTOCOL, - MQTTCLIENT_TRACE_ERROR, - MQTTCLIENT_TRACE_SEVERE, - MQTTCLIENT_TRACE_FATAL, -}; - - -/** - * This function sets the level of trace information which will be - * returned in the trace callback. - * @param level the trace level required - */ -LIBMQTT_API void MQTTClient_setTraceLevel(enum MQTTCLIENT_TRACE_LEVELS level); - - -/** - * This is a callback function prototype which must be implemented if you want - * to receive trace information. Do not invoke any other Paho API calls in this - * callback function - unpredictable behavior may result. - * @param level the trace level of the message returned - * @param message the trace message. This is a pointer to a static buffer which - * will be overwritten on each call. You must copy the data if you want to keep - * it for later. - */ -typedef void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char* message); - -/** - * This function sets the trace callback if needed. If set to NULL, - * no trace information will be returned. The default trace level is - * MQTTASYNC_TRACE_MINIMUM. - * @param callback a pointer to the function which will handle the trace information - */ -LIBMQTT_API void MQTTClient_setTraceCallback(MQTTClient_traceCallback* callback); - -/** - * Sets the timeout value for un/subscribe commands when waiting for the un/suback response from - * the server. Values less than 5000 are not allowed. - * @param handle A valid client handle from a successful call to MQTTClient_create(). - * @param milliSeconds the maximum number of milliseconds to wait - * @return MQTTCLIENT_SUCCESS or MQTTCLIENT_FAILURE - */ -LIBMQTT_API int MQTTClient_setCommandTimeout(MQTTClient handle, unsigned long milliSeconds); - -/** - * Returns a pointer to the string representation of the error or NULL. - * - * Do not free after use. Returns NULL if the error code is unknown. - */ -LIBMQTT_API const char* MQTTClient_strerror(int code); - -#if defined(__cplusplus) - } -#endif - -#endif - -/*! - * @cond MQTTClient_main - * @page async Asynchronous vs synchronous client applications - * This client library supports two modes of operation. These are referred to - * as synchronous and asynchronous modes. If your application - * calls MQTTClient_setCallbacks(), this puts the client into asynchronous - * mode, otherwise it operates in synchronous mode. - * - * In synchronous mode, the client application runs on a single thread. - * Messages are published using the MQTTClient_publish() and - * MQTTClient_publishMessage() functions. To determine that a QoS1 or QoS2 - * (see @ref qos) message has been successfully delivered, the application - * must call the MQTTClient_waitForCompletion() function. An example showing - * synchronous publication is shown in @ref pubsync. Receiving messages in - * synchronous mode uses the MQTTClient_receive() function. Client applications - * must call either MQTTClient_receive() or MQTTClient_yield() relatively - * frequently in order to allow processing of acknowledgements and the MQTT - * "pings" that keep the network connection to the server alive. - * - * In asynchronous mode, the client application runs on several threads. The - * main program calls functions in the client library to publish and subscribe, - * just as for the synchronous mode. Processing of handshaking and maintaining - * the network connection is performed in the background, however. - * Notifications of status and message reception are provided to the client - * application using callbacks registered with the library by the call to - * MQTTClient_setCallbacks() (see MQTTClient_messageArrived(), - * MQTTClient_connectionLost() and MQTTClient_deliveryComplete()). - * This API is not thread safe however - it is not possible to call it from multiple - * threads without synchronization. You can use the MQTTAsync API for that. - * - * @page callbacks Callbacks - * You must not call a function from this API from within a callback otherwise - * a deadlock might result. The only exception to this is the ability to call - * connect within the connection lost callback, to allow a reconnect. - * - * When using MQTT 5.0, you can also call connect from within the disconnected - * callback, which is invoked when the MQTT server sends a disconnect packet. - * This server behaviour is allowed in MQTT 5.0, but not in MQTT 3.1.1, so the - * disconnected callback will never be invoked if you use MQTT 3.1.1. - * - * In particular, you must make a publish call within the message arrived callback. - * These restrictions are all lifted in the - * MQTTAsync API. - * - * If no callbacks are assigned, this will include the message arrived callback. - * This could be done if the application is a pure publisher, and does - * not subscribe to any topics. If however messages are received, and no message - * arrived callback is set, or receive not called, then those messages will accumulate - * and take up memory, as there is no place for them to be delivered. - * It is up to the application to protect against this situation. - * - * @page wildcard Subscription wildcards - * Every MQTT message includes a topic that classifies it. MQTT servers use - * topics to determine which subscribers should receive messages published to - * the server. - * - * Consider the server receiving messages from several environmental sensors. - * Each sensor publishes its measurement data as a message with an associated - * topic. Subscribing applications need to know which sensor originally - * published each received message. A unique topic is thus used to identify - * each sensor and measurement type. Topics such as SENSOR1TEMP, - * SENSOR1HUMIDITY, SENSOR2TEMP and so on achieve this but are not very - * flexible. If additional sensors are added to the system at a later date, - * subscribing applications must be modified to receive them. - * - * To provide more flexibility, MQTT supports a hierarchical topic namespace. - * This allows application designers to organize topics to simplify their - * management. Levels in the hierarchy are delimited by the '/' character, - * such as SENSOR/1/HUMIDITY. Publishers and subscribers use these - * hierarchical topics as already described. - * - * For subscriptions, two wildcard characters are supported: - *
    - *
  • A '#' character represents a complete sub-tree of the hierarchy and - * thus must be the last character in a subscription topic string, such as - * SENSOR/#. This will match any topic starting with SENSOR/, such as - * SENSOR/1/TEMP and SENSOR/2/HUMIDITY.
    • - *
  • A '+' character represents a single level of the hierarchy and is - * used between delimiters. For example, SENSOR/+/TEMP will match - * SENSOR/1/TEMP and SENSOR/2/TEMP.
    • - *
- * Publishers are not allowed to use the wildcard characters in their topic - * names. - * - * Deciding on your topic hierarchy is an important step in your system design. - * - * @page qos Quality of service - * The MQTT protocol provides three qualities of service for delivering - * messages between clients and servers: "at most once", "at least once" and - * "exactly once". - * - * Quality of service (QoS) is an attribute of an individual message being - * published. An application sets the QoS for a specific message by setting the - * MQTTClient_message.qos field to the required value. - * - * A subscribing client can set the maximum quality of service a server uses - * to send messages that match the client subscriptions. The - * MQTTClient_subscribe() and MQTTClient_subscribeMany() functions set this - * maximum. The QoS of a message forwarded to a subscriber thus might be - * different to the QoS given to the message by the original publisher. - * The lower of the two values is used to forward a message. - * - * The three levels are: - * - * QoS0, At most once: The message is delivered at most once, or it - * may not be delivered at all. Its delivery across the network is not - * acknowledged. The message is not stored. The message could be lost if the - * client is disconnected, or if the server fails. QoS0 is the fastest mode of - * transfer. It is sometimes called "fire and forget". - * - * The MQTT protocol does not require servers to forward publications at QoS0 - * to a client. If the client is disconnected at the time the server receives - * the publication, the publication might be discarded, depending on the - * server implementation. - * - * QoS1, At least once: The message is always delivered at least once. - * It might be delivered multiple times if there is a failure before an - * acknowledgment is received by the sender. The message must be stored - * locally at the sender, until the sender receives confirmation that the - * message has been published by the receiver. The message is stored in case - * the message must be sent again. - * - * QoS2, Exactly once: The message is always delivered exactly once. - * The message must be stored locally at the sender, until the sender receives - * confirmation that the message has been published by the receiver. The - * message is stored in case the message must be sent again. QoS2 is the - * safest, but slowest mode of transfer. A more sophisticated handshaking - * and acknowledgement sequence is used than for QoS1 to ensure no duplication - * of messages occurs. - * @page pubsync Synchronous publication example -@code -#include -#include -#include -#include "MQTTClient.h" - -#define ADDRESS "tcp://mqtt.eclipseprojects.io:1883" -#define CLIENTID "ExampleClientPub" -#define TOPIC "MQTT Examples" -#define PAYLOAD "Hello World!" -#define QOS 1 -#define TIMEOUT 10000L - -int main(int argc, char* argv[]) -{ - MQTTClient client; - MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer; - MQTTClient_message pubmsg = MQTTClient_message_initializer; - MQTTClient_deliveryToken token; - int rc; - - if ((rc = MQTTClient_create(&client, ADDRESS, CLIENTID, - MQTTCLIENT_PERSISTENCE_NONE, NULL)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to create client, return code %d\n", rc); - exit(EXIT_FAILURE); - } - - conn_opts.keepAliveInterval = 20; - conn_opts.cleansession = 1; - if ((rc = MQTTClient_connect(client, &conn_opts)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to connect, return code %d\n", rc); - exit(EXIT_FAILURE); - } - - pubmsg.payload = PAYLOAD; - pubmsg.payloadlen = (int)strlen(PAYLOAD); - pubmsg.qos = QOS; - pubmsg.retained = 0; - if ((rc = MQTTClient_publishMessage(client, TOPIC, &pubmsg, &token)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to publish message, return code %d\n", rc); - exit(EXIT_FAILURE); - } - - printf("Waiting for up to %d seconds for publication of %s\n" - "on topic %s for client with ClientID: %s\n", - (int)(TIMEOUT/1000), PAYLOAD, TOPIC, CLIENTID); - rc = MQTTClient_waitForCompletion(client, token, TIMEOUT); - printf("Message with delivery token %d delivered\n", token); - - if ((rc = MQTTClient_disconnect(client, 10000)) != MQTTCLIENT_SUCCESS) - printf("Failed to disconnect, return code %d\n", rc); - MQTTClient_destroy(&client); - return rc; -} - - * @endcode - * - * @page pubasync Asynchronous publication example -@code{.c} -#include -#include -#include -#include "MQTTClient.h" - -#if !defined(_WIN32) -#include -#else -#include -#endif - -#define ADDRESS "tcp://mqtt.eclipseprojects.io:1883" -#define CLIENTID "ExampleClientPub" -#define TOPIC "MQTT Examples" -#define PAYLOAD "Hello World!" -#define QOS 1 -#define TIMEOUT 10000L - -MQTTClient_deliveryToken deliveredtoken; - -void delivered(void *context, MQTTClient_deliveryToken dt) -{ - printf("Message with token value %d delivery confirmed\n", dt); - deliveredtoken = dt; -} - -int msgarrvd(void *context, char *topicName, int topicLen, MQTTClient_message *message) -{ - printf("Message arrived\n"); - printf(" topic: %s\n", topicName); - printf(" message: %.*s\n", message->payloadlen, (char*)message->payload); - MQTTClient_freeMessage(&message); - MQTTClient_free(topicName); - return 1; -} - -void connlost(void *context, char *cause) -{ - printf("\nConnection lost\n"); - printf(" cause: %s\n", cause); -} - -int main(int argc, char* argv[]) -{ - MQTTClient client; - MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer; - MQTTClient_message pubmsg = MQTTClient_message_initializer; - MQTTClient_deliveryToken token; - int rc; - - if ((rc = MQTTClient_create(&client, ADDRESS, CLIENTID, - MQTTCLIENT_PERSISTENCE_NONE, NULL)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to create client, return code %d\n", rc); - rc = EXIT_FAILURE; - goto exit; - } - - if ((rc = MQTTClient_setCallbacks(client, NULL, connlost, msgarrvd, delivered)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to set callbacks, return code %d\n", rc); - rc = EXIT_FAILURE; - goto destroy_exit; - } - - conn_opts.keepAliveInterval = 20; - conn_opts.cleansession = 1; - if ((rc = MQTTClient_connect(client, &conn_opts)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to connect, return code %d\n", rc); - rc = EXIT_FAILURE; - goto destroy_exit; - } - - pubmsg.payload = PAYLOAD; - pubmsg.payloadlen = (int)strlen(PAYLOAD); - pubmsg.qos = QOS; - pubmsg.retained = 0; - deliveredtoken = 0; - if ((rc = MQTTClient_publishMessage(client, TOPIC, &pubmsg, &token)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to publish message, return code %d\n", rc); - rc = EXIT_FAILURE; - } - else - { - printf("Waiting for publication of %s\n" - "on topic %s for client with ClientID: %s\n", - PAYLOAD, TOPIC, CLIENTID); - while (deliveredtoken != token) - { - #if defined(_WIN32) - Sleep(100); - #else - usleep(10000L); - #endif - } - } - - if ((rc = MQTTClient_disconnect(client, 10000)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to disconnect, return code %d\n", rc); - rc = EXIT_FAILURE; - } - -destroy_exit: - MQTTClient_destroy(&client); - -exit: - return rc; -} - - * @endcode - * @page subasync Asynchronous subscription example -@code -#include -#include -#include -#include "MQTTClient.h" - -#define ADDRESS "tcp://mqtt.eclipseprojects.io:1883" -#define CLIENTID "ExampleClientSub" -#define TOPIC "MQTT Examples" -#define PAYLOAD "Hello World!" -#define QOS 1 -#define TIMEOUT 10000L - -volatile MQTTClient_deliveryToken deliveredtoken; - -void delivered(void *context, MQTTClient_deliveryToken dt) -{ - printf("Message with token value %d delivery confirmed\n", dt); - deliveredtoken = dt; -} - -int msgarrvd(void *context, char *topicName, int topicLen, MQTTClient_message *message) -{ - printf("Message arrived\n"); - printf(" topic: %s\n", topicName); - printf(" message: %.*s\n", message->payloadlen, (char*)message->payload); - MQTTClient_freeMessage(&message); - MQTTClient_free(topicName); - return 1; -} - -void connlost(void *context, char *cause) -{ - printf("\nConnection lost\n"); - printf(" cause: %s\n", cause); -} - -int main(int argc, char* argv[]) -{ - MQTTClient client; - MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer; - int rc; - - if ((rc = MQTTClient_create(&client, ADDRESS, CLIENTID, - MQTTCLIENT_PERSISTENCE_NONE, NULL)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to create client, return code %d\n", rc); - rc = EXIT_FAILURE; - goto exit; - } - - if ((rc = MQTTClient_setCallbacks(client, NULL, connlost, msgarrvd, delivered)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to set callbacks, return code %d\n", rc); - rc = EXIT_FAILURE; - goto destroy_exit; - } - - conn_opts.keepAliveInterval = 20; - conn_opts.cleansession = 1; - if ((rc = MQTTClient_connect(client, &conn_opts)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to connect, return code %d\n", rc); - rc = EXIT_FAILURE; - goto destroy_exit; - } - - printf("Subscribing to topic %s\nfor client %s using QoS%d\n\n" - "Press Q to quit\n\n", TOPIC, CLIENTID, QOS); - if ((rc = MQTTClient_subscribe(client, TOPIC, QOS)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to subscribe, return code %d\n", rc); - rc = EXIT_FAILURE; - } - else - { - int ch; - do - { - ch = getchar(); - } while (ch!='Q' && ch != 'q'); - - if ((rc = MQTTClient_unsubscribe(client, TOPIC)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to unsubscribe, return code %d\n", rc); - rc = EXIT_FAILURE; - } - } - - if ((rc = MQTTClient_disconnect(client, 10000)) != MQTTCLIENT_SUCCESS) - { - printf("Failed to disconnect, return code %d\n", rc); - rc = EXIT_FAILURE; - } -destroy_exit: - MQTTClient_destroy(&client); -exit: - return rc; -} - - * @endcode - * @page tracing Tracing - * - * Runtime tracing is controlled by environment variables. - * - * Tracing is switched on by setting MQTT_C_CLIENT_TRACE. A value of ON, or stdout, prints to - * stdout, any other value is interpreted as a file name to use. - * - * The amount of trace detail is controlled with the MQTT_C_CLIENT_TRACE_LEVEL environment - * variable - valid values are ERROR, PROTOCOL, MINIMUM, MEDIUM and MAXIMUM - * (from least to most verbose). - * - * The variable MQTT_C_CLIENT_TRACE_MAX_LINES limits the number of lines of trace that are output - * to a file. Two files are used at most, when they are full, the last one is overwritten with the - * new trace entries. The default size is 1000 lines. - * - * ### MQTT Packet Tracing - * - * A feature that can be very useful is printing the MQTT packets that are sent and received. To - * achieve this, use the following environment variable settings: - * @code - MQTT_C_CLIENT_TRACE=ON - MQTT_C_CLIENT_TRACE_LEVEL=PROTOCOL - * @endcode - * The output you should see looks like this: - * @code - 20130528 155936.813 3 stdout-subscriber -> CONNECT cleansession: 1 (0) - 20130528 155936.813 3 stdout-subscriber <- CONNACK rc: 0 - 20130528 155936.813 3 stdout-subscriber -> SUBSCRIBE msgid: 1 (0) - 20130528 155936.813 3 stdout-subscriber <- SUBACK msgid: 1 - 20130528 155941.818 3 stdout-subscriber -> DISCONNECT (0) - * @endcode - * where the fields are: - * 1. date - * 2. time - * 3. socket number - * 4. client id - * 5. direction (-> from client to server, <- from server to client) - * 6. packet details - * - * ### Default Level Tracing - * - * This is an extract of a default level trace of a call to connect: - * @code - 19700101 010000.000 (1152206656) (0)> MQTTClient_connect:893 - 19700101 010000.000 (1152206656) (1)> MQTTClient_connectURI:716 - 20130528 160447.479 Connecting to serverURI localhost:1883 - 20130528 160447.479 (1152206656) (2)> MQTTProtocol_connect:98 - 20130528 160447.479 (1152206656) (3)> MQTTProtocol_addressPort:48 - 20130528 160447.479 (1152206656) (3)< MQTTProtocol_addressPort:73 - 20130528 160447.479 (1152206656) (3)> Socket_new:599 - 20130528 160447.479 New socket 4 for localhost, port 1883 - 20130528 160447.479 (1152206656) (4)> Socket_addSocket:163 - 20130528 160447.479 (1152206656) (5)> Socket_setnonblocking:73 - 20130528 160447.479 (1152206656) (5)< Socket_setnonblocking:78 (0) - 20130528 160447.479 (1152206656) (4)< Socket_addSocket:176 (0) - 20130528 160447.479 (1152206656) (4)> Socket_error:95 - 20130528 160447.479 (1152206656) (4)< Socket_error:104 (115) - 20130528 160447.479 Connect pending - 20130528 160447.479 (1152206656) (3)< Socket_new:683 (115) - 20130528 160447.479 (1152206656) (2)< MQTTProtocol_connect:131 (115) - * @endcode - * where the fields are: - * 1. date - * 2. time - * 3. thread id - * 4. function nesting level - * 5. function entry (>) or exit (<) - * 6. function name : line of source code file - * 7. return value (if there is one) - * - * ### Memory Allocation Tracing - * - * Setting the trace level to maximum causes memory allocations and frees to be traced along with - * the default trace entries, with messages like the following: - * @code - 20130528 161819.657 Allocating 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 177 ptr 0x179f930 - - 20130528 161819.657 Freeing 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 201, heap use now 896 bytes - * @endcode - * When the last MQTT client object is destroyed, if the trace is being recorded - * and all memory allocated by the client library has not been freed, an error message will be - * written to the trace. This can help with fixing memory leaks. The message will look like this: - * @code - 20130528 163909.208 Some memory not freed at shutdown, possible memory leak - 20130528 163909.208 Heap scan start, total 880 bytes - 20130528 163909.208 Heap element size 32, line 354, file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c, ptr 0x260cb00 - 20130528 163909.208 Content - 20130528 163909.209 Heap scan end - * @endcode - * @endcond - */ diff --git a/MQTTClientPersistence.h b/MQTTClientPersistence.h deleted file mode 100644 index d3caae4..0000000 --- a/MQTTClientPersistence.h +++ /dev/null @@ -1,277 +0,0 @@ -/******************************************************************************* - * Copyright (c) 2009, 2020 IBM Corp. - * - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v2.0 - * and Eclipse Distribution License v1.0 which accompany this distribution. - * - * The Eclipse Public License is available at - * https://www.eclipse.org/legal/epl-2.0/ - * and the Eclipse Distribution License is available at - * http://www.eclipse.org/org/documents/edl-v10.php. - * - * Contributors: - * Ian Craggs - initial API and implementation and/or initial documentation - *******************************************************************************/ - -/** - * @file - * \brief This structure represents a persistent data store, used to store - * outbound and inbound messages, in order to achieve reliable messaging. - * - * The MQTT Client persists QoS1 and QoS2 messages in order to meet the - * assurances of delivery associated with these @ref qos levels. The messages - * are saved in persistent storage - * The type and context of the persistence implementation are specified when - * the MQTT client is created (see MQTTClient_create()). The default - * persistence type (::MQTTCLIENT_PERSISTENCE_DEFAULT) uses a file system-based - * persistence mechanism. The persistence_context argument passed to - * MQTTClient_create() when using the default peristence is a string - * representing the location of the persistence directory. If the context - * argument is NULL, the working directory will be used. - * - * To use memory-based persistence, an application passes - * ::MQTTCLIENT_PERSISTENCE_NONE as the persistence_type to - * MQTTClient_create(). This can lead to message loss in certain situations, - * but can be appropriate in some cases (see @ref qos). - * - * Client applications can provide their own persistence mechanism by passing - * ::MQTTCLIENT_PERSISTENCE_USER as the persistence_type. To implement a - * custom persistence mechanism, the application must pass an initialized - * ::MQTTClient_persistence structure as the persistence_context - * argument to MQTTClient_create(). - * - * If the functions defined return an ::MQTTCLIENT_PERSISTENCE_ERROR then the - * state of the persisted data should remain as it was prior to the function - * being called. For example, if Persistence_put() returns - * ::MQTTCLIENT_PERSISTENCE_ERROR, then it is assumed tha tthe persistent store - * does not contain the data that was passed to the function. Similarly, if - * Persistence_remove() returns ::MQTTCLIENT_PERSISTENCE_ERROR then it is - * assumed that the data to be removed is still held in the persistent store. - * - * It is up to the persistence implementation to log any error information that - * may be required to diagnose a persistence mechanism failure. - */ - -/* -/// @cond EXCLUDE -*/ -#if !defined(MQTTCLIENTPERSISTENCE_H) -#define MQTTCLIENTPERSISTENCE_H -/* -/// @endcond -*/ - -/** - * This persistence_type value specifies the default file system-based - * persistence mechanism (see MQTTClient_create()). - */ -#define MQTTCLIENT_PERSISTENCE_DEFAULT 0 -/** - * This persistence_type value specifies a memory-based - * persistence mechanism (see MQTTClient_create()). - */ -#define MQTTCLIENT_PERSISTENCE_NONE 1 -/** - * This persistence_type value specifies an application-specific - * persistence mechanism (see MQTTClient_create()). - */ -#define MQTTCLIENT_PERSISTENCE_USER 2 - -/** - * Application-specific persistence functions must return this error code if - * there is a problem executing the function. - */ -#define MQTTCLIENT_PERSISTENCE_ERROR -2 - -/** - * @brief Initialize the persistent store. - * - * Either open the existing persistent store for this client ID or create a new - * one if one doesn't exist. If the persistent store is already open, return - * without taking any action. - * - * An application can use the same client identifier to connect to many - * different servers. The clientid in conjunction with the - * serverURI uniquely identifies the persistence store required. - * - * @param handle The address of a pointer to a handle for this persistence - * implementation. This function must set handle to a valid reference to the - * persistence following a successful return. - * The handle pointer is passed as an argument to all the other - * persistence functions. It may include the context parameter and/or any other - * data for use by the persistence functions. - * @param clientID The client identifier for which the persistent store should - * be opened. - * @param serverURI The connection string specified when the MQTT client was - * created (see MQTTClient_create()). - * @param context A pointer to any data required to initialize the persistent - * store (see ::MQTTClient_persistence). - * @return Return 0 if the function completes successfully, otherwise return - * ::MQTTCLIENT_PERSISTENCE_ERROR. - */ -typedef int (*Persistence_open)(void** handle, const char* clientID, const char* serverURI, void* context); - -/** - * @brief Close the persistent store referred to by the handle. - * - * @param handle The handle pointer from a successful call to - * Persistence_open(). - * @return Return 0 if the function completes successfully, otherwise return - * ::MQTTCLIENT_PERSISTENCE_ERROR. - */ -typedef int (*Persistence_close)(void* handle); - -/** - * @brief Put the specified data into the persistent store. - * - * @param handle The handle pointer from a successful call to - * Persistence_open(). - * @param key A string used as the key for the data to be put in the store. The - * key is later used to retrieve data from the store with Persistence_get(). - * @param bufcount The number of buffers to write to the persistence store. - * @param buffers An array of pointers to the data buffers associated with - * this key. - * @param buflens An array of lengths of the data buffers. buflen[n] - * gives the length of buffer[n]. - * @return Return 0 if the function completes successfully, otherwise return - * ::MQTTCLIENT_PERSISTENCE_ERROR. - */ -typedef int (*Persistence_put)(void* handle, char* key, int bufcount, char* buffers[], int buflens[]); - -/** - * @brief Retrieve the specified data from the persistent store. - * - * @param handle The handle pointer from a successful call to - * Persistence_open(). - * @param key A string that is the key for the data to be retrieved. This is - * the same key used to save the data to the store with Persistence_put(). - * @param buffer The address of a pointer to a buffer. This function sets the - * pointer to point at the retrieved data, if successful. - * @param buflen The address of an int that is set to the length of - * buffer by this function if successful. - * @return Return 0 if the function completes successfully, otherwise return - * ::MQTTCLIENT_PERSISTENCE_ERROR. - */ -typedef int (*Persistence_get)(void* handle, char* key, char** buffer, int* buflen); - -/** - * @brief Remove the data for the specified key from the store. - * - * @param handle The handle pointer from a successful call to - * Persistence_open(). - * @param key A string that is the key for the data to be removed from the - * store. This is the same key used to save the data to the store with - * Persistence_put(). - * @return Return 0 if the function completes successfully, otherwise return - * ::MQTTCLIENT_PERSISTENCE_ERROR. - */ -typedef int (*Persistence_remove)(void* handle, char* key); - -/** - * @brief Returns the keys in this persistent data store. - * - * @param handle The handle pointer from a successful call to - * Persistence_open(). - * @param keys The address of a pointer to pointers to strings. Assuming - * successful execution, this function allocates memory to hold the returned - * keys (strings used to store the data with Persistence_put()). It also - * allocates memory to hold an array of pointers to these strings. keys - * is set to point to the array of pointers to strings. - * @param nkeys A pointer to the number of keys in this persistent data store. - * This function sets the number of keys, if successful. - * @return Return 0 if the function completes successfully, otherwise return - * ::MQTTCLIENT_PERSISTENCE_ERROR. - */ -typedef int (*Persistence_keys)(void* handle, char*** keys, int* nkeys); - -/** - * @brief Clears the persistence store, so that it no longer contains any - * persisted data. - * - * @param handle The handle pointer from a successful call to - * Persistence_open(). - * @return Return 0 if the function completes successfully, otherwise return - * ::MQTTCLIENT_PERSISTENCE_ERROR. - */ -typedef int (*Persistence_clear)(void* handle); - -/** - * @brief Returns whether any data has been persisted using the specified key. - * - * @param handle The handle pointer from a successful call to - * Persistence_open(). - * @param key The string to be tested for existence in the store. - * @return Return 0 if the key was found in the store, otherwise return - * ::MQTTCLIENT_PERSISTENCE_ERROR. - */ -typedef int (*Persistence_containskey)(void* handle, char* key); - -/** - * @brief A structure containing the function pointers to a persistence - * implementation and the context or state that will be shared across all - * the persistence functions. - */ -typedef struct { - /** - * A pointer to any data required to initialize the persistent store. - */ - void* context; - /** - * A function pointer to an implementation of Persistence_open(). - */ - Persistence_open popen; - /** - * A function pointer to an implementation of Persistence_close(). - */ - Persistence_close pclose; - /** - * A function pointer to an implementation of Persistence_put(). - */ - Persistence_put pput; - /** - * A function pointer to an implementation of Persistence_get(). - */ - Persistence_get pget; - /** - * A function pointer to an implementation of Persistence_remove(). - */ - Persistence_remove premove; - /** - * A function pointer to an implementation of Persistence_keys(). - */ - Persistence_keys pkeys; - /** - * A function pointer to an implementation of Persistence_clear(). - */ - Persistence_clear pclear; - /** - * A function pointer to an implementation of Persistence_containskey(). - */ - Persistence_containskey pcontainskey; -} MQTTClient_persistence; - - -/** - * A callback which is invoked just before a write to persistence. This can be - * used to transform the data, for instance to encrypt it. - * @param context The context as set in ::MQTTAsync_setBeforePersistenceWrite - * @param bufcount The number of buffers to write to the persistence store. - * @param buffers An array of pointers to the data buffers. - * @param buflens An array of lengths of the data buffers. - * @return Return 0 if the function completes successfully, otherwise non 0. - */ -typedef int MQTTPersistence_beforeWrite(void* context, int bufcount, char* buffers[], int buflens[]); - - -/** - * A callback which is invoked just after a read from persistence. This can be - * used to transform the data, for instance to decrypt it. - * @param context The context as set in ::MQTTAsync_setAfterPersistenceRead - * @param buffer The address of a pointer to a buffer. - * @param buflen The address of an int that is the length of the buffer. - * @return Return 0 if the function completes successfully, otherwise non 0. - */ -typedef int MQTTPersistence_afterRead(void* context, char** buffer, int* buflen); - -#endif diff --git a/MQTTExportDeclarations.h b/MQTTExportDeclarations.h deleted file mode 100644 index d492ef1..0000000 --- a/MQTTExportDeclarations.h +++ /dev/null @@ -1,36 +0,0 @@ -/******************************************************************************* - * Copyright (c) 2020, 2020 Andreas Walter - * - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v2.0 - * and Eclipse Distribution License v1.0 which accompany this distribution. - * - * The Eclipse Public License is available at - * https://www.eclipse.org/legal/epl-2.0/ - * and the Eclipse Distribution License is available at - * http://www.eclipse.org/org/documents/edl-v10.php. - * - * Contributors: - * Andreas Walter - initially moved export declarations into separate fle - *******************************************************************************/ - -#if !defined(EXPORTDECLARATIONS_H) -#define EXPORTDECLARATIONS_H - -#if defined(_WIN32) || defined(_WIN64) -# if defined(PAHO_MQTT_EXPORTS) -# define LIBMQTT_API __declspec(dllexport) -# elif defined(PAHO_MQTT_IMPORTS) -# define LIBMQTT_API __declspec(dllimport) -# else -# define LIBMQTT_API -# endif -#else -# if defined(PAHO_MQTT_EXPORTS) -# define LIBMQTT_API __attribute__ ((visibility ("default"))) -# else -# define LIBMQTT_API extern -# endif -#endif - -#endif diff --git a/MQTTProperties.h b/MQTTProperties.h deleted file mode 100644 index bbfd732..0000000 --- a/MQTTProperties.h +++ /dev/null @@ -1,222 +0,0 @@ -/******************************************************************************* - * Copyright (c) 2017, 2023 IBM Corp. and others - * - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v2.0 - * and Eclipse Distribution License v1.0 which accompany this distribution. - * - * The Eclipse Public License is available at - * https://www.eclipse.org/legal/epl-2.0/ - * and the Eclipse Distribution License is available at - * http://www.eclipse.org/org/documents/edl-v10.php. - * - * Contributors: - * Ian Craggs - initial API and implementation and/or initial documentation - *******************************************************************************/ - -#if !defined(MQTTPROPERTIES_H) -#define MQTTPROPERTIES_H - -#include "MQTTExportDeclarations.h" - -#define MQTT_INVALID_PROPERTY_ID -2 - -/** The one byte MQTT V5 property indicator */ -enum MQTTPropertyCodes { - MQTTPROPERTY_CODE_PAYLOAD_FORMAT_INDICATOR = 1, /**< The value is 1 */ - MQTTPROPERTY_CODE_MESSAGE_EXPIRY_INTERVAL = 2, /**< The value is 2 */ - MQTTPROPERTY_CODE_CONTENT_TYPE = 3, /**< The value is 3 */ - MQTTPROPERTY_CODE_RESPONSE_TOPIC = 8, /**< The value is 8 */ - MQTTPROPERTY_CODE_CORRELATION_DATA = 9, /**< The value is 9 */ - MQTTPROPERTY_CODE_SUBSCRIPTION_IDENTIFIER = 11, /**< The value is 11 */ - MQTTPROPERTY_CODE_SESSION_EXPIRY_INTERVAL = 17, /**< The value is 17 */ - MQTTPROPERTY_CODE_ASSIGNED_CLIENT_IDENTIFER = 18,/**< The value is 18 */ - MQTTPROPERTY_CODE_SERVER_KEEP_ALIVE = 19, /**< The value is 19 */ - MQTTPROPERTY_CODE_AUTHENTICATION_METHOD = 21, /**< The value is 21 */ - MQTTPROPERTY_CODE_AUTHENTICATION_DATA = 22, /**< The value is 22 */ - MQTTPROPERTY_CODE_REQUEST_PROBLEM_INFORMATION = 23,/**< The value is 23 */ - MQTTPROPERTY_CODE_WILL_DELAY_INTERVAL = 24, /**< The value is 24 */ - MQTTPROPERTY_CODE_REQUEST_RESPONSE_INFORMATION = 25,/**< The value is 25 */ - MQTTPROPERTY_CODE_RESPONSE_INFORMATION = 26, /**< The value is 26 */ - MQTTPROPERTY_CODE_SERVER_REFERENCE = 28, /**< The value is 28 */ - MQTTPROPERTY_CODE_REASON_STRING = 31, /**< The value is 31 */ - MQTTPROPERTY_CODE_RECEIVE_MAXIMUM = 33, /**< The value is 33*/ - MQTTPROPERTY_CODE_TOPIC_ALIAS_MAXIMUM = 34, /**< The value is 34 */ - MQTTPROPERTY_CODE_TOPIC_ALIAS = 35, /**< The value is 35 */ - MQTTPROPERTY_CODE_MAXIMUM_QOS = 36, /**< The value is 36 */ - MQTTPROPERTY_CODE_RETAIN_AVAILABLE = 37, /**< The value is 37 */ - MQTTPROPERTY_CODE_USER_PROPERTY = 38, /**< The value is 38 */ - MQTTPROPERTY_CODE_MAXIMUM_PACKET_SIZE = 39, /**< The value is 39 */ - MQTTPROPERTY_CODE_WILDCARD_SUBSCRIPTION_AVAILABLE = 40,/**< The value is 40 */ - MQTTPROPERTY_CODE_SUBSCRIPTION_IDENTIFIERS_AVAILABLE = 41,/**< The value is 41 */ - MQTTPROPERTY_CODE_SHARED_SUBSCRIPTION_AVAILABLE = 42/**< The value is 241 */ -}; - -/** - * Returns a printable string description of an MQTT V5 property code. - * @param value an MQTT V5 property code. - * @return the printable string description of the input property code. - * NULL if the code was not found. - */ -LIBMQTT_API const char* MQTTPropertyName(enum MQTTPropertyCodes value); - -/** The one byte MQTT V5 property type */ -enum MQTTPropertyTypes { - MQTTPROPERTY_TYPE_BYTE, - MQTTPROPERTY_TYPE_TWO_BYTE_INTEGER, - MQTTPROPERTY_TYPE_FOUR_BYTE_INTEGER, - MQTTPROPERTY_TYPE_VARIABLE_BYTE_INTEGER, - MQTTPROPERTY_TYPE_BINARY_DATA, - MQTTPROPERTY_TYPE_UTF_8_ENCODED_STRING, - MQTTPROPERTY_TYPE_UTF_8_STRING_PAIR -}; - -/** - * Returns the MQTT V5 type code of an MQTT V5 property. - * @param value an MQTT V5 property code. - * @return the MQTT V5 type code of the input property. -1 if the code was not found. - */ -LIBMQTT_API int MQTTProperty_getType(enum MQTTPropertyCodes value); - -/** - * The data for a length delimited string - */ -typedef struct -{ - int len; /**< the length of the string */ - char* data; /**< pointer to the string data */ -} MQTTLenString; - - -/** - * Structure to hold an MQTT version 5 property of any type - */ -typedef struct -{ - enum MQTTPropertyCodes identifier; /**< The MQTT V5 property id. A multi-byte integer. */ - /** The value of the property, as a union of the different possible types. */ - union { - unsigned char byte; /**< holds the value of a byte property type */ - unsigned short integer2; /**< holds the value of a 2 byte integer property type */ - unsigned int integer4; /**< holds the value of a 4 byte integer property type */ - struct { - MQTTLenString data; /**< The value of a string property, or the name of a user property. */ - MQTTLenString value; /**< The value of a user property. */ - }; - } value; -} MQTTProperty; - -/** - * MQTT version 5 property list - */ -typedef struct MQTTProperties -{ - int count; /**< number of property entries in the array */ - int max_count; /**< max number of properties that the currently allocated array can store */ - int length; /**< mbi: byte length of all properties */ - MQTTProperty *array; /**< array of properties */ -} MQTTProperties; - -#define MQTTProperties_initializer {0, 0, 0, NULL} - -/** - * Returns the length of the properties structure when serialized ready for network transmission. - * @param props an MQTT V5 property structure. - * @return the length in bytes of the properties when serialized. - */ -int MQTTProperties_len(MQTTProperties* props); - -/** - * Add a property pointer to the property array. Memory is allocated in this function, - * so MQTTClient_create or MQTTAsync_create must be called first to initialize the - * internal heap tracking. Alternatively MQTTAsync_global_init() can be called first - * or build with the HIGH_PERFORMANCE option which disables the heap tracking. - * @param props The property list to add the property to. - * @param prop The property to add to the list. - * @return 0 on success, -1 on failure. - */ -LIBMQTT_API int MQTTProperties_add(MQTTProperties* props, const MQTTProperty* prop); - -/** - * Serialize the given property list to a character buffer, e.g. for writing to the network. - * @param pptr pointer to the buffer - move the pointer as we add data - * @param properties pointer to the property list, can be NULL - * @return whether the write succeeded or not: number of bytes written, or < 0 on failure. - */ -int MQTTProperties_write(char** pptr, const MQTTProperties* properties); - -/** - * Reads a property list from a character buffer into an array. - * @param properties pointer to the property list to be filled. Should be initalized but empty. - * @param pptr pointer to the character buffer. - * @param enddata pointer to the end of the character buffer so we don't read beyond. - * @return 1 if the properties were read successfully. - */ -int MQTTProperties_read(MQTTProperties* properties, char** pptr, char* enddata); - -/** - * Free all memory allocated to the property list, including any to individual properties. - * @param properties pointer to the property list. - */ -LIBMQTT_API void MQTTProperties_free(MQTTProperties* properties); - -/** - * Copy the contents of a property list, allocating additional memory if needed. - * @param props pointer to the property list. - * @return the duplicated property list. - */ -LIBMQTT_API MQTTProperties MQTTProperties_copy(const MQTTProperties* props); - -/** - * Checks if property list contains a specific property. - * @param props pointer to the property list. - * @param propid the property id to check for. - * @return 1 if found, 0 if not. - */ -LIBMQTT_API int MQTTProperties_hasProperty(MQTTProperties *props, enum MQTTPropertyCodes propid); - -/** - * Returns the number of instances of a property id. Most properties can exist only once. - * User properties and subscription ids can exist more than once. - * @param props pointer to the property list. - * @param propid the property id to check for. - * @return the number of times found. Can be 0. - */ -LIBMQTT_API int MQTTProperties_propertyCount(MQTTProperties *props, enum MQTTPropertyCodes propid); - -/** - * Returns the integer value of a specific property. The property given must be a numeric type. - * @param props pointer to the property list. - * @param propid the property id to check for. - * @return the integer value of the property. -9999999 on failure. - */ -LIBMQTT_API int MQTTProperties_getNumericValue(MQTTProperties *props, enum MQTTPropertyCodes propid); - -/** - * Returns the integer value of a specific property when it's not the only instance. - * The property given must be a numeric type. - * @param props pointer to the property list. - * @param propid the property id to check for. - * @param index the instance number, starting at 0. - * @return the integer value of the property. -9999999 on failure. - */ -LIBMQTT_API int MQTTProperties_getNumericValueAt(MQTTProperties *props, enum MQTTPropertyCodes propid, int index); - -/** - * Returns a pointer to the property structure for a specific property. - * @param props pointer to the property list. - * @param propid the property id to check for. - * @return the pointer to the property structure if found. NULL if not found. - */ -LIBMQTT_API MQTTProperty* MQTTProperties_getProperty(MQTTProperties *props, enum MQTTPropertyCodes propid); - -/** - * Returns a pointer to the property structure for a specific property when it's not the only instance. - * @param props pointer to the property list. - * @param propid the property id to check for. - * @param index the instance number, starting at 0. - * @return the pointer to the property structure if found. NULL if not found. - */ -LIBMQTT_API MQTTProperty* MQTTProperties_getPropertyAt(MQTTProperties *props, enum MQTTPropertyCodes propid, int index); - -#endif /* MQTTPROPERTIES_H */ diff --git a/MQTTReasonCodes.h b/MQTTReasonCodes.h deleted file mode 100644 index 2dc08ea..0000000 --- a/MQTTReasonCodes.h +++ /dev/null @@ -1,79 +0,0 @@ -/******************************************************************************* - * Copyright (c) 2017, 2020 IBM Corp. and others - * - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v2.0 - * and Eclipse Distribution License v1.0 which accompany this distribution. - * - * The Eclipse Public License is available at - * https://www.eclipse.org/legal/epl-2.0/ - * and the Eclipse Distribution License is available at - * http://www.eclipse.org/org/documents/edl-v10.php. - * - * Contributors: - * Ian Craggs - initial API and implementation and/or initial documentation - *******************************************************************************/ - -#if !defined(MQTTREASONCODES_H) -#define MQTTREASONCODES_H - -#include "MQTTExportDeclarations.h" - -/** The MQTT V5 one byte reason code */ -enum MQTTReasonCodes { - MQTTREASONCODE_SUCCESS = 0, - MQTTREASONCODE_NORMAL_DISCONNECTION = 0, - MQTTREASONCODE_GRANTED_QOS_0 = 0, - MQTTREASONCODE_GRANTED_QOS_1 = 1, - MQTTREASONCODE_GRANTED_QOS_2 = 2, - MQTTREASONCODE_DISCONNECT_WITH_WILL_MESSAGE = 4, - MQTTREASONCODE_NO_MATCHING_SUBSCRIBERS = 16, - MQTTREASONCODE_NO_SUBSCRIPTION_FOUND = 17, - MQTTREASONCODE_CONTINUE_AUTHENTICATION = 24, - MQTTREASONCODE_RE_AUTHENTICATE = 25, - MQTTREASONCODE_UNSPECIFIED_ERROR = 128, - MQTTREASONCODE_MALFORMED_PACKET = 129, - MQTTREASONCODE_PROTOCOL_ERROR = 130, - MQTTREASONCODE_IMPLEMENTATION_SPECIFIC_ERROR = 131, - MQTTREASONCODE_UNSUPPORTED_PROTOCOL_VERSION = 132, - MQTTREASONCODE_CLIENT_IDENTIFIER_NOT_VALID = 133, - MQTTREASONCODE_BAD_USER_NAME_OR_PASSWORD = 134, - MQTTREASONCODE_NOT_AUTHORIZED = 135, - MQTTREASONCODE_SERVER_UNAVAILABLE = 136, - MQTTREASONCODE_SERVER_BUSY = 137, - MQTTREASONCODE_BANNED = 138, - MQTTREASONCODE_SERVER_SHUTTING_DOWN = 139, - MQTTREASONCODE_BAD_AUTHENTICATION_METHOD = 140, - MQTTREASONCODE_KEEP_ALIVE_TIMEOUT = 141, - MQTTREASONCODE_SESSION_TAKEN_OVER = 142, - MQTTREASONCODE_TOPIC_FILTER_INVALID = 143, - MQTTREASONCODE_TOPIC_NAME_INVALID = 144, - MQTTREASONCODE_PACKET_IDENTIFIER_IN_USE = 145, - MQTTREASONCODE_PACKET_IDENTIFIER_NOT_FOUND = 146, - MQTTREASONCODE_RECEIVE_MAXIMUM_EXCEEDED = 147, - MQTTREASONCODE_TOPIC_ALIAS_INVALID = 148, - MQTTREASONCODE_PACKET_TOO_LARGE = 149, - MQTTREASONCODE_MESSAGE_RATE_TOO_HIGH = 150, - MQTTREASONCODE_QUOTA_EXCEEDED = 151, - MQTTREASONCODE_ADMINISTRATIVE_ACTION = 152, - MQTTREASONCODE_PAYLOAD_FORMAT_INVALID = 153, - MQTTREASONCODE_RETAIN_NOT_SUPPORTED = 154, - MQTTREASONCODE_QOS_NOT_SUPPORTED = 155, - MQTTREASONCODE_USE_ANOTHER_SERVER = 156, - MQTTREASONCODE_SERVER_MOVED = 157, - MQTTREASONCODE_SHARED_SUBSCRIPTIONS_NOT_SUPPORTED = 158, - MQTTREASONCODE_CONNECTION_RATE_EXCEEDED = 159, - MQTTREASONCODE_MAXIMUM_CONNECT_TIME = 160, - MQTTREASONCODE_SUBSCRIPTION_IDENTIFIERS_NOT_SUPPORTED = 161, - MQTTREASONCODE_WILDCARD_SUBSCRIPTIONS_NOT_SUPPORTED = 162 -}; - -/** - * Returns a printable string description of an MQTT V5 reason code. - * @param value an MQTT V5 reason code. - * @return the printable string description of the input reason code. - * NULL if the code was not found. - */ -LIBMQTT_API const char* MQTTReasonCode_toString(enum MQTTReasonCodes value); - -#endif diff --git a/MQTTSubscribeOpts.h b/MQTTSubscribeOpts.h deleted file mode 100644 index 264e4d0..0000000 --- a/MQTTSubscribeOpts.h +++ /dev/null @@ -1,46 +0,0 @@ -/******************************************************************************* - * Copyright (c) 2018 IBM Corp. - * - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v2.0 - * and Eclipse Distribution License v1.0 which accompany this distribution. - * - * The Eclipse Public License is available at - * https://www.eclipse.org/legal/epl-2.0/ - * and the Eclipse Distribution License is available at - * http://www.eclipse.org/org/documents/edl-v10.php. - * - * Contributors: - * Ian Craggs - initial API and implementation and/or initial documentation - *******************************************************************************/ - -#if !defined(SUBOPTS_H) -#define SUBOPTS_H - -/** The MQTT V5 subscribe options, apart from QoS which existed before V5. */ -typedef struct MQTTSubscribe_options -{ - /** The eyecatcher for this structure. Must be MQSO. */ - char struct_id[4]; - /** The version number of this structure. Must be 0. - */ - int struct_version; - /** To not receive our own publications, set to 1. - * 0 is the original MQTT behaviour - all messages matching the subscription are received. - */ - unsigned char noLocal; - /** To keep the retain flag as on the original publish message, set to 1. - * If 0, defaults to the original MQTT behaviour where the retain flag is only set on - * publications sent by a broker if in response to a subscribe request. - */ - unsigned char retainAsPublished; - /** 0 - send retained messages at the time of the subscribe (original MQTT behaviour) - * 1 - send retained messages on subscribe only if the subscription is new - * 2 - do not send retained messages at all - */ - unsigned char retainHandling; -} MQTTSubscribe_options; - -#define MQTTSubscribe_options_initializer { {'M', 'Q', 'S', 'O'}, 0, 0, 0, 0 } - -#endif diff --git a/XAprs b/XAprs deleted file mode 100644 index 7dc9a42..0000000 Binary files a/XAprs and /dev/null differ diff --git a/debian/changelog b/debian/changelog index 9d7cb6e..c2f7600 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,9 +1,9 @@ -linbpq (6.0.24.51.2+repack+really.50-1~hibbian+1) UNRELEASED; urgency=medium +linbpq (6.0.24.51.3+repack+really50-1~hibbian+1) bookworm-hibbian-unstable; urgency=medium * Build .50 under new build system * Emergency update to avoid buffer overflows - -- Dave Hibberd Sat, 30 Nov 2024 11:21:25 +0000 + -- Dave Hibberd Sat, 30 Nov 2024 11:46:27 +0000 linbpq (6.0.24.50-1~hibbian+1) bookworm-hibbian-unstable; urgency=medium diff --git a/debian/lintian-overrides b/debian/lintian-overrides index 1e12a54..468a093 100644 --- a/debian/lintian-overrides +++ b/debian/lintian-overrides @@ -1,18 +1,11 @@ # weirdness from oarc packaging linbpq: dir-or-file-in-opt [opt/oarc/] linbpq: dir-or-file-in-opt [opt/oarc/bpq/] -# these are ok, just held within the program -linbpq: embedded-library libminiupnpc [usr/sbin/linbpq] -linbpq: embedded-library libpng [usr/sbin/linbpq] # i know! linbpq: no-manual-page [usr/sbin/linbpq] -# Build fails -linbpq: hardening-no-bindnow [usr/sbin/linbpq] # Directory is populated on first run linbpq: package-contains-empty-directory [opt/oarc/bpq/] # Code convenience linbpq: spelling-error-in-binary Dont Don't [usr/sbin/linbpq] linbpq: spelling-error-in-binary Paramters Parameters [usr/sbin/linbpq] -linbpq: spelling-error-in-binary WiH With [usr/sbin/linbpq] -linbpq: spelling-error-in-binary lable label [usr/sbin/linbpq] linbpq: spelling-error-in-binary lon long [usr/sbin/linbpq] diff --git a/debian/patches/dynamic-links b/debian/patches/dynamic-links new file mode 100644 index 0000000..d097a47 --- /dev/null +++ b/debian/patches/dynamic-links @@ -0,0 +1,44 @@ +--- a/LinBPQ.c ++++ b/LinBPQ.c +@@ -717,7 +717,7 @@ + + } + +-#include "getopt.h" ++#include + + static struct option long_options[] = + { +--- a/DRATS.c ++++ b/DRATS.c +@@ -563,7 +563,7 @@ + #define ZEXPORT __stdcall + #endif + +-#include "zlib.h" ++#include + + + int doinflate(unsigned char * source, unsigned char * dest, int Len, int destlen, int * outLen) +--- a/HTTPcode.c ++++ b/HTTPcode.c +@@ -38,7 +38,7 @@ + #define ZEXPORT __stdcall + #endif + +-#include "zlib.h" ++#include + + #define CKernel + #include "httpconnectioninfo.h" +--- a/IPCode.c ++++ b/IPCode.c +@@ -97,8 +97,6 @@ + + #include "pcap.h" + +-int pcap_sendpacket(pcap_t *p, u_char *buf, int size); +- + #ifndef LINBPQ + #include "kernelresource.h" + LRESULT CALLBACK ResWndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam); diff --git a/debian/patches/series b/debian/patches/series index 90fc185..67af30c 100644 --- a/debian/patches/series +++ b/debian/patches/series @@ -2,3 +2,4 @@ headers.patch ftbfs-gcc14.patch spelling-errors.patch makefile +dynamic-links diff --git a/debian/source/lintian-overrides b/debian/source/lintian-overrides index a39267e..e69de29 100644 --- a/debian/source/lintian-overrides +++ b/debian/source/lintian-overrides @@ -1,3 +0,0 @@ -# i don't care that much on this -linbpq source: source-contains-prebuilt-windows-binary [PG/Loop.exe] -linbpq source: source-contains-prebuilt-windows-binary [PG/PGTest.exe] diff --git a/igd_desc_parse.h b/igd_desc_parse.h deleted file mode 100644 index 0de546b..0000000 --- a/igd_desc_parse.h +++ /dev/null @@ -1,49 +0,0 @@ -/* $Id: igd_desc_parse.h,v 1.12 2014/11/17 17:19:13 nanard Exp $ */ -/* Project : miniupnp - * http://miniupnp.free.fr/ - * Author : Thomas Bernard - * Copyright (c) 2005-2014 Thomas Bernard - * This software is subject to the conditions detailed in the - * LICENCE file provided in this distribution. - * */ -#ifndef IGD_DESC_PARSE_H_INCLUDED -#define IGD_DESC_PARSE_H_INCLUDED - -/* Structure to store the result of the parsing of UPnP - * descriptions of Internet Gateway Devices */ -#define MINIUPNPC_URL_MAXSIZE (128) -struct IGDdatas_service { - char controlurl[MINIUPNPC_URL_MAXSIZE]; - char eventsuburl[MINIUPNPC_URL_MAXSIZE]; - char scpdurl[MINIUPNPC_URL_MAXSIZE]; - char servicetype[MINIUPNPC_URL_MAXSIZE]; - /*char devicetype[MINIUPNPC_URL_MAXSIZE];*/ -}; - -struct IGDdatas { - char cureltname[MINIUPNPC_URL_MAXSIZE]; - char urlbase[MINIUPNPC_URL_MAXSIZE]; - char presentationurl[MINIUPNPC_URL_MAXSIZE]; - int level; - /*int state;*/ - /* "urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1" */ - struct IGDdatas_service CIF; - /* "urn:schemas-upnp-org:service:WANIPConnection:1" - * "urn:schemas-upnp-org:service:WANPPPConnection:1" */ - struct IGDdatas_service first; - /* if both WANIPConnection and WANPPPConnection are present */ - struct IGDdatas_service second; - /* "urn:schemas-upnp-org:service:WANIPv6FirewallControl:1" */ - struct IGDdatas_service IPv6FC; - /* tmp */ - struct IGDdatas_service tmp; -}; - -void IGDstartelt(void *, const char *, int); -void IGDendelt(void *, const char *, int); -void IGDdata(void *, const char *, int); -#ifdef DEBUG -void printIGD(struct IGDdatas *); -#endif /* DEBUG */ - -#endif /* IGD_DESC_PARSE_H_INCLUDED */ diff --git a/miniupnpc.h b/miniupnpc.h deleted file mode 100644 index 5a9b7c5..0000000 --- a/miniupnpc.h +++ /dev/null @@ -1,153 +0,0 @@ -/* $Id: miniupnpc.h,v 1.56 2020/12/20 18:07:35 nanard Exp $ */ -/* vim: tabstop=4 shiftwidth=4 noexpandtab - * Project: miniupnp - * http://miniupnp.free.fr/ - * Author: Thomas Bernard - * Copyright (c) 2005-2018 Thomas Bernard - * This software is subjects to the conditions detailed - * in the LICENCE file provided within this distribution */ -#ifndef MINIUPNPC_H_INCLUDED -#define MINIUPNPC_H_INCLUDED - -#include "miniupnpc_declspec.h" -#include "igd_desc_parse.h" -#include "upnpdev.h" - -/* error codes : */ -#define UPNPDISCOVER_SUCCESS (0) -#define UPNPDISCOVER_UNKNOWN_ERROR (-1) -#define UPNPDISCOVER_SOCKET_ERROR (-101) -#define UPNPDISCOVER_MEMORY_ERROR (-102) - -/* versions : */ -#define MINIUPNPC_VERSION "2.2.2" -#define MINIUPNPC_API_VERSION 17 - -/* Source port: - Using "1" as an alias for 1900 for backwards compatibility - (presuming one would have used that for the "sameport" parameter) */ -#define UPNP_LOCAL_PORT_ANY 0 -#define UPNP_LOCAL_PORT_SAME 1 - -#ifdef __cplusplus -extern "C" { -#endif - -/* Structures definitions : */ -struct UPNParg { const char * elt; const char * val; }; - -char * -simpleUPnPcommand(int, const char *, const char *, - const char *, struct UPNParg *, - int *); - -/* upnpDiscover() - * discover UPnP devices on the network. - * The discovered devices are returned as a chained list. - * It is up to the caller to free the list with freeUPNPDevlist(). - * delay (in millisecond) is the maximum time for waiting any device - * response. - * If available, device list will be obtained from MiniSSDPd. - * Default path for minissdpd socket will be used if minissdpdsock argument - * is NULL. - * If multicastif is not NULL, it will be used instead of the default - * multicast interface for sending SSDP discover packets. - * If localport is set to UPNP_LOCAL_PORT_SAME(1) SSDP packets will be sent - * from the source port 1900 (same as destination port), if set to - * UPNP_LOCAL_PORT_ANY(0) system assign a source port, any other value will - * be attempted as the source port. - * "searchalltypes" parameter is useful when searching several types, - * if 0, the discovery will stop with the first type returning results. - * TTL should default to 2. */ -MINIUPNP_LIBSPEC struct UPNPDev * -upnpDiscover(int delay, const char * multicastif, - const char * minissdpdsock, int localport, - int ipv6, unsigned char ttl, - int * error); - -MINIUPNP_LIBSPEC struct UPNPDev * -upnpDiscoverAll(int delay, const char * multicastif, - const char * minissdpdsock, int localport, - int ipv6, unsigned char ttl, - int * error); - -MINIUPNP_LIBSPEC struct UPNPDev * -upnpDiscoverDevice(const char * device, int delay, const char * multicastif, - const char * minissdpdsock, int localport, - int ipv6, unsigned char ttl, - int * error); - -MINIUPNP_LIBSPEC struct UPNPDev * -upnpDiscoverDevices(const char * const deviceTypes[], - int delay, const char * multicastif, - const char * minissdpdsock, int localport, - int ipv6, unsigned char ttl, - int * error, - int searchalltypes); - -/* parserootdesc() : - * parse root XML description of a UPnP device and fill the IGDdatas - * structure. */ -MINIUPNP_LIBSPEC void parserootdesc(const char *, int, struct IGDdatas *); - -/* structure used to get fast access to urls - * controlURL: controlURL of the WANIPConnection - * ipcondescURL: url of the description of the WANIPConnection - * controlURL_CIF: controlURL of the WANCommonInterfaceConfig - * controlURL_6FC: controlURL of the WANIPv6FirewallControl - */ -struct UPNPUrls { - char * controlURL; - char * ipcondescURL; - char * controlURL_CIF; - char * controlURL_6FC; - char * rootdescURL; -}; - -/* UPNP_GetValidIGD() : - * return values : - * 0 = NO IGD found - * 1 = A valid connected IGD has been found - * 2 = A valid IGD has been found but it reported as - * not connected - * 3 = an UPnP device has been found but was not recognized as an IGD - * - * In any non zero return case, the urls and data structures - * passed as parameters are set. Donc forget to call FreeUPNPUrls(urls) to - * free allocated memory. - */ -MINIUPNP_LIBSPEC int -UPNP_GetValidIGD(struct UPNPDev * devlist, - struct UPNPUrls * urls, - struct IGDdatas * data, - char * lanaddr, int lanaddrlen); - -/* UPNP_GetIGDFromUrl() - * Used when skipping the discovery process. - * When succeding, urls, data, and lanaddr arguments are set. - * return value : - * 0 - Not ok - * 1 - OK */ -MINIUPNP_LIBSPEC int -UPNP_GetIGDFromUrl(const char * rootdescurl, - struct UPNPUrls * urls, - struct IGDdatas * data, - char * lanaddr, int lanaddrlen); - -MINIUPNP_LIBSPEC void -GetUPNPUrls(struct UPNPUrls *, struct IGDdatas *, - const char *, unsigned int); - -MINIUPNP_LIBSPEC void -FreeUPNPUrls(struct UPNPUrls *); - -/* return 0 or 1 */ -MINIUPNP_LIBSPEC int UPNPIGD_IsConnected(struct UPNPUrls *, struct IGDdatas *); - - -#ifdef __cplusplus -} -#endif - -#endif - diff --git a/miniupnpctypes.h b/miniupnpctypes.h deleted file mode 100644 index 591c32f..0000000 --- a/miniupnpctypes.h +++ /dev/null @@ -1,19 +0,0 @@ -/* $Id: miniupnpctypes.h,v 1.2 2012/09/27 15:42:10 nanard Exp $ */ -/* Miniupnp project : http://miniupnp.free.fr/ or http://miniupnp.tuxfamily.org - * Author : Thomas Bernard - * Copyright (c) 2011 Thomas Bernard - * This software is subject to the conditions detailed in the - * LICENCE file provided within this distribution */ -#ifndef MINIUPNPCTYPES_H_INCLUDED -#define MINIUPNPCTYPES_H_INCLUDED - -#if (defined __STDC_VERSION__ && __STDC_VERSION__ >= 199901L) -#define UNSIGNED_INTEGER unsigned long long -#define STRTOUI strtoull -#else -#define UNSIGNED_INTEGER unsigned int -#define STRTOUI strtoul -#endif - -#endif - diff --git a/pcap.h b/pcap.h deleted file mode 100644 index fa67dba..0000000 --- a/pcap.h +++ /dev/null @@ -1,257 +0,0 @@ -/* -*- Mode: c; tab-width: 8; indent-tabs-mode: 1; c-basic-offset: 8; -*- */ -/* - * Copyright (c) 1993, 1994, 1995, 1996, 1997 - * The Regents of the University of California. All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * 3. All advertising materials mentioning features or use of this software - * must display the following acknowledgement: - * This product includes software developed by the Computer Systems - * Engineering Group at Lawrence Berkeley Laboratory. - * 4. Neither the name of the University nor of the Laboratory may be used - * to endorse or promote products derived from this software without - * specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * - * @(#) $Header: /tcpdump/master/libpcap/pcap.h,v 1.45.2.3 2003/11/21 10:20:50 guy Exp $ (LBL) - */ - -#ifndef lib_pcap_h -#define lib_pcap_h - -#ifdef WIN32 -//#include "pcap-stdinc.h" -#else /* WIN32 */ -#include -#include -#endif /* WIN32 */ - -#ifndef PCAP_DONT_INCLUDE_PCAP_BPF_H -#include "pcap-bpf.h" -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -#define PCAP_VERSION_MAJOR 2 -#define PCAP_VERSION_MINOR 4 - -#define PCAP_ERRBUF_SIZE 256 - -/* - * Compatibility for systems that have a bpf.h that - * predates the bpf typedefs for 64-bit support. - */ -#if BPF_RELEASE - 0 < 199406 -typedef int bpf_int32; -typedef u_int bpf_u_int32; -#endif - -typedef struct pcap pcap_t; -typedef struct pcap_dumper pcap_dumper_t; -typedef struct pcap_if pcap_if_t; -typedef struct pcap_addr pcap_addr_t; - -/* - * The first record in the file contains saved values for some - * of the flags used in the printout phases of tcpdump. - * Many fields here are 32 bit ints so compilers won't insert unwanted - * padding; these files need to be interchangeable across architectures. - * - * Do not change the layout of this structure, in any way (this includes - * changes that only affect the length of fields in this structure). - * - * Also, do not change the interpretation of any of the members of this - * structure, in any way (this includes using values other than - * LINKTYPE_ values, as defined in "savefile.c", in the "linktype" - * field). - * - * Instead: - * - * introduce a new structure for the new format, if the layout - * of the structure changed; - * - * send mail to "tcpdump-workers@tcpdump.org", requesting a new - * magic number for your new capture file format, and, when - * you get the new magic number, put it in "savefile.c"; - * - * use that magic number for save files with the changed file - * header; - * - * make the code in "savefile.c" capable of reading files with - * the old file header as well as files with the new file header - * (using the magic number to determine the header format). - * - * Then supply the changes to "patches@tcpdump.org", so that future - * versions of libpcap and programs that use it (such as tcpdump) will - * be able to read your new capture file format. - */ -struct pcap_file_header { - bpf_u_int32 magic; - u_short version_major; - u_short version_minor; - bpf_int32 thiszone; /* gmt to local correction */ - bpf_u_int32 sigfigs; /* accuracy of timestamps */ - bpf_u_int32 snaplen; /* max length saved portion of each pkt */ - bpf_u_int32 linktype; /* data link type (LINKTYPE_*) */ -}; - -/* - * Each packet in the dump file is prepended with this generic header. - * This gets around the problem of different headers for different - * packet interfaces. - */ -struct pcap_pkthdr { - struct timeval ts; /* time stamp */ - bpf_u_int32 caplen; /* length of portion present */ - bpf_u_int32 len; /* length this packet (off wire) */ -}; - -/* - * As returned by the pcap_stats() - */ -struct pcap_stat { - u_int ps_recv; /* number of packets received */ - u_int ps_drop; /* number of packets dropped */ - u_int ps_ifdrop; /* drops by interface XXX not yet supported */ -#ifdef WIN32 - u_int bs_capt; /* number of packets that reach the application */ -#endif /* WIN32 */ -}; - -/* - * Item in a list of interfaces. - */ -struct pcap_if { - struct pcap_if *next; - char *name; /* name to hand to "pcap_open_live()" */ - char *description; /* textual description of interface, or NULL */ - struct pcap_addr *addresses; - bpf_u_int32 flags; /* PCAP_IF_ interface flags */ -}; - -#define PCAP_IF_LOOPBACK 0x00000001 /* interface is loopback */ - -/* - * Representation of an interface address. - */ -struct pcap_addr { - struct pcap_addr *next; - struct sockaddr *addr; /* address */ - struct sockaddr *netmask; /* netmask for that address */ - struct sockaddr *broadaddr; /* broadcast address for that address */ - struct sockaddr *dstaddr; /* P2P destination address for that address */ -}; - -typedef void (*pcap_handler)(u_char *, const struct pcap_pkthdr *, - const u_char *); - -char *pcap_lookupdev(char *); -int pcap_lookupnet(const char *, bpf_u_int32 *, bpf_u_int32 *, char *); -pcap_t *pcap_open_live(const char *, int, int, int, char *); -pcap_t *pcap_open_dead(int, int); -pcap_t *pcap_open_offline(const char *, char *); -void pcap_close(pcap_t *); -int pcap_loop(pcap_t *, int, pcap_handler, u_char *); -int pcap_dispatch(pcap_t *, int, pcap_handler, u_char *); -const u_char* - pcap_next(pcap_t *, struct pcap_pkthdr *); -int pcap_next_ex(pcap_t *, struct pcap_pkthdr **, const u_char **); -void pcap_breakloop(pcap_t *); -int pcap_stats(pcap_t *, struct pcap_stat *); -int pcap_setfilter(pcap_t *, struct bpf_program *); -int pcap_getnonblock(pcap_t *, char *); -int pcap_setnonblock(pcap_t *, int, char *); -void pcap_perror(pcap_t *, char *); -char *pcap_strerror(int); -char *pcap_geterr(pcap_t *); -int pcap_compile(pcap_t *, struct bpf_program *, char *, int, - bpf_u_int32); -int pcap_compile_nopcap(int, int, struct bpf_program *, - char *, int, bpf_u_int32); -void pcap_freecode(struct bpf_program *); -int pcap_datalink(pcap_t *); -int pcap_list_datalinks(pcap_t *, int **); -int pcap_set_datalink(pcap_t *, int); -int pcap_datalink_name_to_val(const char *); -const char *pcap_datalink_val_to_name(int); -const char *pcap_datalink_val_to_description(int); -int pcap_snapshot(pcap_t *); -int pcap_is_swapped(pcap_t *); -int pcap_major_version(pcap_t *); -int pcap_minor_version(pcap_t *); - -/* XXX */ -FILE *pcap_file(pcap_t *); -int pcap_fileno(pcap_t *); - -pcap_dumper_t *pcap_dump_open(pcap_t *, const char *); -int pcap_dump_flush(pcap_dumper_t *); -void pcap_dump_close(pcap_dumper_t *); -void pcap_dump(u_char *, const struct pcap_pkthdr *, const u_char *); -FILE *pcap_dump_file(pcap_dumper_t *); - -int pcap_findalldevs(pcap_if_t **, char *); -void pcap_freealldevs(pcap_if_t *); - -const char *pcap_lib_version(void); - -/* XXX this guy lives in the bpf tree */ -u_int bpf_filter(struct bpf_insn *, u_char *, u_int, u_int); -int bpf_validate(struct bpf_insn *f, int len); -char *bpf_image(struct bpf_insn *, int); -void bpf_dump(struct bpf_program *, int); - -#ifdef WIN32 -/* - * Win32 definitions - */ - -int pcap_setbuff(pcap_t *p, int dim); -int pcap_setmode(pcap_t *p, int mode); -int pcap_sendpacket(pcap_t *p, u_char *buf, int size); -int pcap_setmintocopy(pcap_t *p, int size); - -#ifdef WPCAP -/* Include file with the wpcap-specific extensions */ -#include -#endif - -#define MODE_CAPT 0 -#define MODE_STAT 1 - -#else -/* - * UN*X definitions - */ - -int pcap_get_selectable_fd(pcap_t *); - -#endif /* WIN32 */ - -#ifdef __cplusplus -} -#endif - -#endif diff --git a/upnpcommands.h b/upnpcommands.h deleted file mode 100644 index 994104e..0000000 --- a/upnpcommands.h +++ /dev/null @@ -1,348 +0,0 @@ -/* $Id: upnpcommands.h,v 1.33 2019/02/10 12:29:25 nanard Exp $ */ -/* Miniupnp project : http://miniupnp.free.fr/ - * Author : Thomas Bernard - * Copyright (c) 2005-2018 Thomas Bernard - * This software is subject to the conditions detailed in the - * LICENCE file provided within this distribution */ -#ifndef UPNPCOMMANDS_H_INCLUDED -#define UPNPCOMMANDS_H_INCLUDED - -#include "miniupnpc_declspec.h" -#include "miniupnpctypes.h" - -/* MiniUPnPc return codes : */ -#define UPNPCOMMAND_SUCCESS (0) -#define UPNPCOMMAND_UNKNOWN_ERROR (-1) -#define UPNPCOMMAND_INVALID_ARGS (-2) -#define UPNPCOMMAND_HTTP_ERROR (-3) -#define UPNPCOMMAND_INVALID_RESPONSE (-4) -#define UPNPCOMMAND_MEM_ALLOC_ERROR (-5) - -#ifdef __cplusplus -extern "C" { -#endif - -struct PortMappingParserData; - -MINIUPNP_LIBSPEC UNSIGNED_INTEGER -UPNP_GetTotalBytesSent(const char * controlURL, - const char * servicetype); - -MINIUPNP_LIBSPEC UNSIGNED_INTEGER -UPNP_GetTotalBytesReceived(const char * controlURL, - const char * servicetype); - -MINIUPNP_LIBSPEC UNSIGNED_INTEGER -UPNP_GetTotalPacketsSent(const char * controlURL, - const char * servicetype); - -MINIUPNP_LIBSPEC UNSIGNED_INTEGER -UPNP_GetTotalPacketsReceived(const char * controlURL, - const char * servicetype); - -/* UPNP_GetStatusInfo() - * status and lastconnerror are 64 byte buffers - * Return values : - * UPNPCOMMAND_SUCCESS, UPNPCOMMAND_INVALID_ARGS, UPNPCOMMAND_UNKNOWN_ERROR - * or a UPnP Error code */ -MINIUPNP_LIBSPEC int -UPNP_GetStatusInfo(const char * controlURL, - const char * servicetype, - char * status, - unsigned int * uptime, - char * lastconnerror); - -/* UPNP_GetConnectionTypeInfo() - * argument connectionType is a 64 character buffer - * Return Values : - * UPNPCOMMAND_SUCCESS, UPNPCOMMAND_INVALID_ARGS, UPNPCOMMAND_UNKNOWN_ERROR - * or a UPnP Error code */ -MINIUPNP_LIBSPEC int -UPNP_GetConnectionTypeInfo(const char * controlURL, - const char * servicetype, - char * connectionType); - -/* UPNP_GetExternalIPAddress() call the corresponding UPNP method. - * if the third arg is not null the value is copied to it. - * at least 16 bytes must be available - * - * Return values : - * 0 : SUCCESS - * NON ZERO : ERROR Either an UPnP error code or an unknown error. - * - * possible UPnP Errors : - * 402 Invalid Args - See UPnP Device Architecture section on Control. - * 501 Action Failed - See UPnP Device Architecture section on Control. */ -MINIUPNP_LIBSPEC int -UPNP_GetExternalIPAddress(const char * controlURL, - const char * servicetype, - char * extIpAdd); - -/* UPNP_GetLinkLayerMaxBitRates() - * call WANCommonInterfaceConfig:1#GetCommonLinkProperties - * - * return values : - * UPNPCOMMAND_SUCCESS, UPNPCOMMAND_INVALID_ARGS, UPNPCOMMAND_UNKNOWN_ERROR - * or a UPnP Error Code. */ -MINIUPNP_LIBSPEC int -UPNP_GetLinkLayerMaxBitRates(const char* controlURL, - const char* servicetype, - unsigned int * bitrateDown, - unsigned int * bitrateUp); - -/* UPNP_AddPortMapping() - * if desc is NULL, it will be defaulted to "libminiupnpc" - * remoteHost is usually NULL because IGD don't support it. - * - * Return values : - * 0 : SUCCESS - * NON ZERO : ERROR. Either an UPnP error code or an unknown error. - * - * List of possible UPnP errors for AddPortMapping : - * errorCode errorDescription (short) - Description (long) - * 402 Invalid Args - See UPnP Device Architecture section on Control. - * 501 Action Failed - See UPnP Device Architecture section on Control. - * 606 Action not authorized - The action requested REQUIRES authorization and - * the sender was not authorized. - * 715 WildCardNotPermittedInSrcIP - The source IP address cannot be - * wild-carded - * 716 WildCardNotPermittedInExtPort - The external port cannot be wild-carded - * 718 ConflictInMappingEntry - The port mapping entry specified conflicts - * with a mapping assigned previously to another client - * 724 SamePortValuesRequired - Internal and External port values - * must be the same - * 725 OnlyPermanentLeasesSupported - The NAT implementation only supports - * permanent lease times on port mappings - * 726 RemoteHostOnlySupportsWildcard - RemoteHost must be a wildcard - * and cannot be a specific IP address or DNS name - * 727 ExternalPortOnlySupportsWildcard - ExternalPort must be a wildcard and - * cannot be a specific port value - * 728 NoPortMapsAvailable - There are not enough free ports available to - * complete port mapping. - * 729 ConflictWithOtherMechanisms - Attempted port mapping is not allowed - * due to conflict with other mechanisms. - * 732 WildCardNotPermittedInIntPort - The internal port cannot be wild-carded - */ -MINIUPNP_LIBSPEC int -UPNP_AddPortMapping(const char * controlURL, const char * servicetype, - const char * extPort, - const char * inPort, - const char * inClient, - const char * desc, - const char * proto, - const char * remoteHost, - const char * leaseDuration); - -/* UPNP_AddAnyPortMapping() - * if desc is NULL, it will be defaulted to "libminiupnpc" - * remoteHost is usually NULL because IGD don't support it. - * - * Return values : - * 0 : SUCCESS - * NON ZERO : ERROR. Either an UPnP error code or an unknown error. - * - * List of possible UPnP errors for AddPortMapping : - * errorCode errorDescription (short) - Description (long) - * 402 Invalid Args - See UPnP Device Architecture section on Control. - * 501 Action Failed - See UPnP Device Architecture section on Control. - * 606 Action not authorized - The action requested REQUIRES authorization and - * the sender was not authorized. - * 715 WildCardNotPermittedInSrcIP - The source IP address cannot be - * wild-carded - * 716 WildCardNotPermittedInExtPort - The external port cannot be wild-carded - * 728 NoPortMapsAvailable - There are not enough free ports available to - * complete port mapping. - * 729 ConflictWithOtherMechanisms - Attempted port mapping is not allowed - * due to conflict with other mechanisms. - * 732 WildCardNotPermittedInIntPort - The internal port cannot be wild-carded - */ -MINIUPNP_LIBSPEC int -UPNP_AddAnyPortMapping(const char * controlURL, const char * servicetype, - const char * extPort, - const char * inPort, - const char * inClient, - const char * desc, - const char * proto, - const char * remoteHost, - const char * leaseDuration, - char * reservedPort); - -/* UPNP_DeletePortMapping() - * Use same argument values as what was used for AddPortMapping(). - * remoteHost is usually NULL because IGD don't support it. - * Return Values : - * 0 : SUCCESS - * NON ZERO : error. Either an UPnP error code or an undefined error. - * - * List of possible UPnP errors for DeletePortMapping : - * 402 Invalid Args - See UPnP Device Architecture section on Control. - * 606 Action not authorized - The action requested REQUIRES authorization - * and the sender was not authorized. - * 714 NoSuchEntryInArray - The specified value does not exist in the array */ -MINIUPNP_LIBSPEC int -UPNP_DeletePortMapping(const char * controlURL, const char * servicetype, - const char * extPort, const char * proto, - const char * remoteHost); - -/* UPNP_DeletePortRangeMapping() - * Use same argument values as what was used for AddPortMapping(). - * remoteHost is usually NULL because IGD don't support it. - * Return Values : - * 0 : SUCCESS - * NON ZERO : error. Either an UPnP error code or an undefined error. - * - * List of possible UPnP errors for DeletePortMapping : - * 606 Action not authorized - The action requested REQUIRES authorization - * and the sender was not authorized. - * 730 PortMappingNotFound - This error message is returned if no port - * mapping is found in the specified range. - * 733 InconsistentParameters - NewStartPort and NewEndPort values are not consistent. */ -MINIUPNP_LIBSPEC int -UPNP_DeletePortMappingRange(const char * controlURL, const char * servicetype, - const char * extPortStart, const char * extPortEnd, - const char * proto, - const char * manage); - -/* UPNP_GetPortMappingNumberOfEntries() - * not supported by all routers */ -MINIUPNP_LIBSPEC int -UPNP_GetPortMappingNumberOfEntries(const char * controlURL, - const char * servicetype, - unsigned int * numEntries); - -/* UPNP_GetSpecificPortMappingEntry() - * retrieves an existing port mapping - * params : - * in extPort - * in proto - * in remoteHost - * out intClient (16 bytes) - * out intPort (6 bytes) - * out desc (80 bytes) - * out enabled (4 bytes) - * out leaseDuration (16 bytes) - * - * return value : - * UPNPCOMMAND_SUCCESS, UPNPCOMMAND_INVALID_ARGS, UPNPCOMMAND_UNKNOWN_ERROR - * or a UPnP Error Code. - * - * List of possible UPnP errors for _GetSpecificPortMappingEntry : - * 402 Invalid Args - See UPnP Device Architecture section on Control. - * 501 Action Failed - See UPnP Device Architecture section on Control. - * 606 Action not authorized - The action requested REQUIRES authorization - * and the sender was not authorized. - * 714 NoSuchEntryInArray - The specified value does not exist in the array. - */ -MINIUPNP_LIBSPEC int -UPNP_GetSpecificPortMappingEntry(const char * controlURL, - const char * servicetype, - const char * extPort, - const char * proto, - const char * remoteHost, - char * intClient, - char * intPort, - char * desc, - char * enabled, - char * leaseDuration); - -/* UPNP_GetGenericPortMappingEntry() - * params : - * in index - * out extPort (6 bytes) - * out intClient (16 bytes) - * out intPort (6 bytes) - * out protocol (4 bytes) - * out desc (80 bytes) - * out enabled (4 bytes) - * out rHost (64 bytes) - * out duration (16 bytes) - * - * return value : - * UPNPCOMMAND_SUCCESS, UPNPCOMMAND_INVALID_ARGS, UPNPCOMMAND_UNKNOWN_ERROR - * or a UPnP Error Code. - * - * Possible UPNP Error codes : - * 402 Invalid Args - See UPnP Device Architecture section on Control. - * 606 Action not authorized - The action requested REQUIRES authorization - * and the sender was not authorized. - * 713 SpecifiedArrayIndexInvalid - The specified array index is out of bounds - */ -MINIUPNP_LIBSPEC int -UPNP_GetGenericPortMappingEntry(const char * controlURL, - const char * servicetype, - const char * index, - char * extPort, - char * intClient, - char * intPort, - char * protocol, - char * desc, - char * enabled, - char * rHost, - char * duration); - -/* UPNP_GetListOfPortMappings() Available in IGD v2 - * - * - * Possible UPNP Error codes : - * 606 Action not Authorized - * 730 PortMappingNotFound - no port mapping is found in the specified range. - * 733 InconsistantParameters - NewStartPort and NewEndPort values are not - * consistent. - */ -MINIUPNP_LIBSPEC int -UPNP_GetListOfPortMappings(const char * controlURL, - const char * servicetype, - const char * startPort, - const char * endPort, - const char * protocol, - const char * numberOfPorts, - struct PortMappingParserData * data); - -/* IGD:2, functions for service WANIPv6FirewallControl:1 */ -MINIUPNP_LIBSPEC int -UPNP_GetFirewallStatus(const char * controlURL, - const char * servicetype, - int * firewallEnabled, - int * inboundPinholeAllowed); - -MINIUPNP_LIBSPEC int -UPNP_GetOutboundPinholeTimeout(const char * controlURL, const char * servicetype, - const char * remoteHost, - const char * remotePort, - const char * intClient, - const char * intPort, - const char * proto, - int * opTimeout); - -MINIUPNP_LIBSPEC int -UPNP_AddPinhole(const char * controlURL, const char * servicetype, - const char * remoteHost, - const char * remotePort, - const char * intClient, - const char * intPort, - const char * proto, - const char * leaseTime, - char * uniqueID); - -MINIUPNP_LIBSPEC int -UPNP_UpdatePinhole(const char * controlURL, const char * servicetype, - const char * uniqueID, - const char * leaseTime); - -MINIUPNP_LIBSPEC int -UPNP_DeletePinhole(const char * controlURL, const char * servicetype, const char * uniqueID); - -MINIUPNP_LIBSPEC int -UPNP_CheckPinholeWorking(const char * controlURL, const char * servicetype, - const char * uniqueID, int * isWorking); - -MINIUPNP_LIBSPEC int -UPNP_GetPinholePackets(const char * controlURL, const char * servicetype, - const char * uniqueID, int * packets); - -#ifdef __cplusplus -} -#endif - -#endif - diff --git a/upnpdev.h b/upnpdev.h deleted file mode 100644 index 9b2cb43..0000000 --- a/upnpdev.h +++ /dev/null @@ -1,44 +0,0 @@ -/* $Id: upnpdev.h,v 1.3 2020/05/29 15:57:42 nanard Exp $ */ -/* Project : miniupnp - * Web : http://miniupnp.free.fr/ or https://miniupnp.tuxfamily.org/ - * Author : Thomas BERNARD - * copyright (c) 2005-2020 Thomas Bernard - * This software is subjet to the conditions detailed in the - * provided LICENSE file. */ -#ifndef UPNPDEV_H_INCLUDED -#define UPNPDEV_H_INCLUDED - -#include "miniupnpc_declspec.h" - -#ifdef __cplusplus -extern "C" { -#endif - -struct UPNPDev { - struct UPNPDev * pNext; - char * descURL; - char * st; - char * usn; - unsigned int scope_id; -#if defined(__STDC_VERSION) && __STDC_VERSION__ >= 199901L - /* C99 flexible array member */ - char buffer[]; -#elif defined(__GNUC__) - char buffer[0]; -#else - /* Fallback to a hack */ - char buffer[1]; -#endif -}; - -/* freeUPNPDevlist() - * free list returned by upnpDiscover() */ -MINIUPNP_LIBSPEC void freeUPNPDevlist(struct UPNPDev * devlist); - - -#ifdef __cplusplus -} -#endif - - -#endif /* UPNPDEV_H_INCLUDED */ diff --git a/upnperrors.h b/upnperrors.h deleted file mode 100644 index 3115aee..0000000 --- a/upnperrors.h +++ /dev/null @@ -1,26 +0,0 @@ -/* $Id: upnperrors.h,v 1.6 2015/07/21 13:16:55 nanard Exp $ */ -/* (c) 2007-2015 Thomas Bernard - * All rights reserved. - * MiniUPnP Project. - * http://miniupnp.free.fr/ or http://miniupnp.tuxfamily.org/ - * This software is subjet to the conditions detailed in the - * provided LICENCE file. */ -#ifndef UPNPERRORS_H_INCLUDED -#define UPNPERRORS_H_INCLUDED - -#include "miniupnpc_declspec.h" - -#ifdef __cplusplus -extern "C" { -#endif - -/* strupnperror() - * Return a string description of the UPnP error code - * or NULL for undefinded errors */ -MINIUPNP_LIBSPEC const char * strupnperror(int err); - -#ifdef __cplusplus -} -#endif - -#endif diff --git a/zconf.h b/zconf.h deleted file mode 100644 index a359cd1..0000000 --- a/zconf.h +++ /dev/null @@ -1,333 +0,0 @@ -/* zconf.h -- configuration of the zlib compression library - * Copyright (C) 1995-2005 Jean-loup Gailly. - * For conditions of distribution and use, see copyright notice in zlib.h - */ - -/* @(#) $Id$ */ - -#ifndef ZCONF_H -#define ZCONF_H - -/* - * If you *really* need a unique prefix for all types and library functions, - * compile with -DZ_PREFIX. The "standard" zlib should be compiled without it. - */ -#ifdef Z_PREFIX -# define deflateInit_ z_deflateInit_ -# define deflate z_deflate -# define deflateEnd z_deflateEnd -# define inflateInit_ z_inflateInit_ -# define inflate z_inflate -# define inflateEnd z_inflateEnd -# define deflateInit2_ z_deflateInit2_ -# define deflateSetDictionary z_deflateSetDictionary -# define deflateCopy z_deflateCopy -# define deflateReset z_deflateReset -# define deflateParams z_deflateParams -# define deflateBound z_deflateBound -# define deflatePrime z_deflatePrime -# define inflateInit2_ z_inflateInit2_ -# define inflateSetDictionary z_inflateSetDictionary -# define inflateSync z_inflateSync -# define inflateSyncPoint z_inflateSyncPoint -# define inflateCopy z_inflateCopy -# define inflateReset z_inflateReset -# define inflateBack z_inflateBack -# define inflateBackEnd z_inflateBackEnd -# define compress z_compress -# define compress2 z_compress2 -# define compressBound z_compressBound -# define uncompress z_uncompress -# define adler32 z_adler32 -# define crc32 z_crc32 -# define get_crc_table z_get_crc_table -# define zError z_zError - -# define alloc_func z_alloc_func -# define free_func z_free_func -# define in_func z_in_func -# define out_func z_out_func -# define Byte z_Byte -# define uInt z_uInt -# define uLong z_uLong -# define Bytef z_Bytef -# define charf z_charf -# define intf z_intf -# define uIntf z_uIntf -# define uLongf z_uLongf -# define voidpf z_voidpf -# define voidp z_voidp -#endif - -#if defined(__MSDOS__) && !defined(MSDOS) -# define MSDOS -#endif -#if (defined(OS_2) || defined(__OS2__)) && !defined(OS2) -# define OS2 -#endif -#if defined(_WINDOWS) && !defined(WINDOWS) -# define WINDOWS -#endif -#if defined(_WIN32) || defined(_WIN32_WCE) || defined(__WIN32__) -# ifndef WIN32 -# define WIN32 -# endif -#endif -#if (defined(MSDOS) || defined(OS2) || defined(WINDOWS)) && !defined(WIN32) -# if !defined(__GNUC__) && !defined(__FLAT__) && !defined(__386__) -# ifndef SYS16BIT -# define SYS16BIT -# endif -# endif -#endif - -/* - * Compile with -DMAXSEG_64K if the alloc function cannot allocate more - * than 64k bytes at a time (needed on systems with 16-bit int). - */ -#ifdef SYS16BIT -# define MAXSEG_64K -#endif -#ifdef MSDOS -# define UNALIGNED_OK -#endif - -#ifdef __STDC_VERSION__ -# ifndef STDC -# define STDC -# endif -# if __STDC_VERSION__ >= 199901L -# ifndef STDC99 -# define STDC99 -# endif -# endif -#endif -#if !defined(STDC) && (defined(__STDC__) || defined(__cplusplus)) -# define STDC -#endif -#if !defined(STDC) && (defined(__GNUC__) || defined(__BORLANDC__)) -# define STDC -#endif -#if !defined(STDC) && (defined(MSDOS) || defined(WINDOWS) || defined(WIN32)) -# define STDC -#endif -#if !defined(STDC) && (defined(OS2) || defined(__HOS_AIX__)) -# define STDC -#endif - -#if defined(__OS400__) && !defined(STDC) /* iSeries (formerly AS/400). */ -# define STDC -#endif - -#ifndef STDC -# ifndef const /* cannot use !defined(STDC) && !defined(const) on Mac */ -# define const /* note: need a more gentle solution here */ -# endif -#endif - -/* Some Mac compilers merge all .h files incorrectly: */ -#if defined(__MWERKS__)||defined(applec)||defined(THINK_C)||defined(__SC__) -# define NO_DUMMY_DECL -#endif - -/* Maximum value for memLevel in deflateInit2 */ -#ifndef MAX_MEM_LEVEL -# ifdef MAXSEG_64K -# define MAX_MEM_LEVEL 8 -# else -# define MAX_MEM_LEVEL 9 -# endif -#endif - -/* Maximum value for windowBits in deflateInit2 and inflateInit2. - * WARNING: reducing MAX_WBITS makes minigzip unable to extract .gz files - * created by gzip. (Files created by minigzip can still be extracted by - * gzip.) - */ -#ifndef MAX_WBITS -# define MAX_WBITS 15 /* 32K LZ77 window */ -#endif - -/* The memory requirements for deflate are (in bytes): - (1 << (windowBits+2)) + (1 << (memLevel+9)) - that is: 128K for windowBits=15 + 128K for memLevel = 8 (default values) - plus a few kilobytes for small objects. For example, if you want to reduce - the default memory requirements from 256K to 128K, compile with - make CFLAGS="-O -DMAX_WBITS=14 -DMAX_MEM_LEVEL=7" - Of course this will generally degrade compression (there's no free lunch). - - The memory requirements for inflate are (in bytes) 1 << windowBits - that is, 32K for windowBits=15 (default value) plus a few kilobytes - for small objects. -*/ - - /* Type declarations */ - -#ifndef OF /* function prototypes */ -# ifdef STDC -# define OF(args) args -# else -# define OF(args) () -# endif -#endif - -/* The following definitions for FAR are needed only for MSDOS mixed - * model programming (small or medium model with some far allocations). - * This was tested only with MSC; for other MSDOS compilers you may have - * to define NO_MEMCPY in zutil.h. If you don't need the mixed model, - * just define FAR to be empty. - */ -#ifdef SYS16BIT -# if defined(M_I86SM) || defined(M_I86MM) - /* MSC small or medium model */ -# define SMALL_MEDIUM -# ifdef _MSC_VER -# define FAR _far -# else -# define FAR far -# endif -# endif -# if (defined(__SMALL__) || defined(__MEDIUM__)) - /* Turbo C small or medium model */ -# define SMALL_MEDIUM -# ifdef __BORLANDC__ -# define FAR _far -# else -# define FAR far -# endif -# endif -#endif - -#if defined(WINDOWS) || defined(WIN32) - /* If building or using zlib as a DLL, define ZLIB_DLL. - * This is not mandatory, but it offers a little performance increase. - */ -# ifdef ZLIB_DLL -# if defined(WIN32) && (!defined(__BORLANDC__) || (__BORLANDC__ >= 0x500)) -# ifdef ZLIB_INTERNAL -# define ZEXTERN extern __declspec(dllexport) -# else -# define ZEXTERN extern __declspec(dllimport) -# endif -# endif -# endif /* ZLIB_DLL */ - /* If building or using zlib with the WINAPI/WINAPIV calling convention, - * define ZLIB_WINAPI. - * Caution: the standard ZLIB1.DLL is NOT compiled using ZLIB_WINAPI. - */ -# ifdef ZLIB_WINAPI -# ifdef FAR -# undef FAR -# endif -# include - /* No need for _export, use ZLIB.DEF instead. */ - /* For complete Windows compatibility, use WINAPI, not __stdcall. */ -# define ZEXPORT WINAPI -# ifdef WIN32 -# define ZEXPORTVA WINAPIV -# else -# define ZEXPORTVA FAR CDECL -# endif -# endif -#endif - - -#if defined (__BEOS__) -# ifdef ZLIB_DLL -# ifdef ZLIB_INTERNAL -# define ZEXPORT __declspec(dllexport) -# define ZEXPORTVA __declspec(dllexport) -# else -# define ZEXPORT __declspec(dllimport) -# define ZEXPORTVA __declspec(dllimport) -# endif -# endif -#endif - -#ifndef ZEXTERN -# define ZEXTERN extern -#endif -#ifndef ZEXPORT -# define ZEXPORT -#endif -#ifndef ZEXPORTVA -# define ZEXPORTVA -#endif - -#ifndef FAR -# define FAR -#endif - -#if !defined(__MACTYPES__) -typedef unsigned char Byte; /* 8 bits */ -#endif -typedef unsigned int uInt; /* 16 bits or more */ -typedef unsigned long uLong; /* 32 bits or more */ - -#ifdef SMALL_MEDIUM - /* Borland C/C++ and some old MSC versions ignore FAR inside typedef */ -# define Bytef Byte FAR -#else - typedef Byte FAR Bytef; -#endif -typedef char FAR charf; -typedef int FAR intf; -typedef uInt FAR uIntf; -typedef uLong FAR uLongf; - -#ifdef STDC - typedef void const *voidpc; - typedef void FAR *voidpf; - typedef void *voidp; -#else - typedef Byte const *voidpc; - typedef Byte FAR *voidpf; - typedef Byte *voidp; -#endif - -#if 0 /* HAVE_UNISTD_H -- this line is updated by ./configure */ -# include /* for off_t */ -# include /* for SEEK_* and off_t */ -# ifdef VMS -# include /* for off_t */ -# endif -# define z_off_t off_t -#endif -#ifndef SEEK_SET -# define SEEK_SET 0 /* Seek from beginning of file. */ -# define SEEK_CUR 1 /* Seek from current position. */ -# define SEEK_END 2 /* Set file pointer to EOF plus "offset" */ -#endif -#ifndef z_off_t -# define z_off_t long -#endif - -#if defined(__OS400__) -# define NO_vsnprintf -#endif - -#if defined(__MVS__) -# define NO_vsnprintf -# ifdef FAR -# undef FAR -# endif -#endif - -/* MVS linker does not support external names larger than 8 bytes */ -#if defined(__MVS__) -# pragma map(deflateInit_,"DEIN") -# pragma map(deflateInit2_,"DEIN2") -# pragma map(deflateEnd,"DEEND") -# pragma map(deflateBound,"DEBND") -# pragma map(inflateInit_,"ININ") -# pragma map(inflateInit2_,"ININ2") -# pragma map(inflateEnd,"INEND") -# pragma map(inflateSync,"INSY") -# pragma map(inflateSetDictionary,"INSEDI") -# pragma map(compressBound,"CMBND") -# pragma map(inflate_table,"INTABL") -# pragma map(inflate_fast,"INFA") -# pragma map(inflate_copyright,"INCOPY") -#endif - -#endif /* ZCONF_H */ diff --git a/zlib.h b/zlib.h deleted file mode 100644 index 10eb981..0000000 --- a/zlib.h +++ /dev/null @@ -1,1358 +0,0 @@ -/* zlib.h -- interface of the 'zlib' general purpose compression library - version 1.2.3, July 18th, 2005 - - Copyright (C) 1995-2005 Jean-loup Gailly and Mark Adler - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. - - Jean-loup Gailly Mark Adler - jloup@gzip.org madler@alumni.caltech.edu - - - The data format used by the zlib library is described by RFCs (Request for - Comments) 1950 to 1952 in the files http://www.ietf.org/rfc/rfc1950.txt - (zlib format), rfc1951.txt (deflate format) and rfc1952.txt (gzip format). -*/ - -#ifndef ZLIB_H -#define ZLIB_H - -#include "zconf.h" - -#ifdef __cplusplus -extern "C" { -#endif - -#define ZLIB_VERSION "1.2.3" -#define ZLIB_VERNUM 0x1230 - -/* - The 'zlib' compression library provides in-memory compression and - decompression functions, including integrity checks of the uncompressed - data. This version of the library supports only one compression method - (deflation) but other algorithms will be added later and will have the same - stream interface. - - Compression can be done in a single step if the buffers are large - enough (for example if an input file is mmap'ed), or can be done by - repeated calls of the compression function. In the latter case, the - application must provide more input and/or consume the output - (providing more output space) before each call. - - The compressed data format used by default by the in-memory functions is - the zlib format, which is a zlib wrapper documented in RFC 1950, wrapped - around a deflate stream, which is itself documented in RFC 1951. - - The library also supports reading and writing files in gzip (.gz) format - with an interface similar to that of stdio using the functions that start - with "gz". The gzip format is different from the zlib format. gzip is a - gzip wrapper, documented in RFC 1952, wrapped around a deflate stream. - - This library can optionally read and write gzip streams in memory as well. - - The zlib format was designed to be compact and fast for use in memory - and on communications channels. The gzip format was designed for single- - file compression on file systems, has a larger header than zlib to maintain - directory information, and uses a different, slower check method than zlib. - - The library does not install any signal handler. The decoder checks - the consistency of the compressed data, so the library should never - crash even in case of corrupted input. -*/ - -typedef voidpf (*alloc_func) OF((voidpf opaque, uInt items, uInt size)); -typedef void (*free_func) OF((voidpf opaque, voidpf address)); - -struct internal_state; - -typedef struct z_stream_s { - Bytef *next_in; /* next input byte */ - uInt avail_in; /* number of bytes available at next_in */ - uLong total_in; /* total nb of input bytes read so far */ - - Bytef *next_out; /* next output byte should be put there */ - uInt avail_out; /* remaining free space at next_out */ - uLong total_out; /* total nb of bytes output so far */ - - char *msg; /* last error message, NULL if no error */ - struct internal_state FAR *state; /* not visible by applications */ - - alloc_func zalloc; /* used to allocate the internal state */ - free_func zfree; /* used to free the internal state */ - voidpf opaque; /* private data object passed to zalloc and zfree */ - - int data_type; /* best guess about the data type: binary or text */ - uLong adler; /* adler32 value of the uncompressed data */ - uLong reserved; /* reserved for future use */ -} z_stream; - -typedef z_stream FAR *z_streamp; - -/* - gzip header information passed to and from zlib routines. See RFC 1952 - for more details on the meanings of these fields. -*/ -typedef struct gz_header_s { - int text; /* true if compressed data believed to be text */ - uLong time; /* modification time */ - int xflags; /* extra flags (not used when writing a gzip file) */ - int os; /* operating system */ - Bytef *extra; /* pointer to extra field or Z_NULL if none */ - uInt extra_len; /* extra field length (valid if extra != Z_NULL) */ - uInt extra_max; /* space at extra (only when reading header) */ - Bytef *name; /* pointer to zero-terminated file name or Z_NULL */ - uInt name_max; /* space at name (only when reading header) */ - Bytef *comment; /* pointer to zero-terminated comment or Z_NULL */ - uInt comm_max; /* space at comment (only when reading header) */ - int hcrc; /* true if there was or will be a header crc */ - int done; /* true when done reading gzip header (not used - when writing a gzip file) */ -} gz_header; - -typedef gz_header FAR *gz_headerp; - -/* - The application must update next_in and avail_in when avail_in has - dropped to zero. It must update next_out and avail_out when avail_out - has dropped to zero. The application must initialize zalloc, zfree and - opaque before calling the init function. All other fields are set by the - compression library and must not be updated by the application. - - The opaque value provided by the application will be passed as the first - parameter for calls of zalloc and zfree. This can be useful for custom - memory management. The compression library attaches no meaning to the - opaque value. - - zalloc must return Z_NULL if there is not enough memory for the object. - If zlib is used in a multi-threaded application, zalloc and zfree must be - thread safe. - - On 16-bit systems, the functions zalloc and zfree must be able to allocate - exactly 65536 bytes, but will not be required to allocate more than this - if the symbol MAXSEG_64K is defined (see zconf.h). WARNING: On MSDOS, - pointers returned by zalloc for objects of exactly 65536 bytes *must* - have their offset normalized to zero. The default allocation function - provided by this library ensures this (see zutil.c). To reduce memory - requirements and avoid any allocation of 64K objects, at the expense of - compression ratio, compile the library with -DMAX_WBITS=14 (see zconf.h). - - The fields total_in and total_out can be used for statistics or - progress reports. After compression, total_in holds the total size of - the uncompressed data and may be saved for use in the decompressor - (particularly if the decompressor wants to decompress everything in - a single step). -*/ - - /* constants */ - -#define Z_NO_FLUSH 0 -#define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */ -#define Z_SYNC_FLUSH 2 -#define Z_FULL_FLUSH 3 -#define Z_FINISH 4 -#define Z_BLOCK 5 -/* Allowed flush values; see deflate() and inflate() below for details */ - -#define Z_OK 0 -#define Z_STREAM_END 1 -#define Z_NEED_DICT 2 -#define Z_ERRNO (-1) -#define Z_STREAM_ERROR (-2) -#define Z_DATA_ERROR (-3) -#define Z_MEM_ERROR (-4) -#define Z_BUF_ERROR (-5) -#define Z_VERSION_ERROR (-6) -/* Return codes for the compression/decompression functions. Negative - * values are errors, positive values are used for special but normal events. - */ - -#define Z_NO_COMPRESSION 0 -#define Z_BEST_SPEED 1 -#define Z_BEST_COMPRESSION 9 -#define Z_DEFAULT_COMPRESSION (-1) -/* compression levels */ - -#define Z_FILTERED 1 -#define Z_HUFFMAN_ONLY 2 -#define Z_RLE 3 -#define Z_FIXED 4 -#define Z_DEFAULT_STRATEGY 0 -/* compression strategy; see deflateInit2() below for details */ - -#define Z_BINARY 0 -#define Z_TEXT 1 -#define Z_ASCII Z_TEXT /* for compatibility with 1.2.2 and earlier */ -#define Z_UNKNOWN 2 -/* Possible values of the data_type field (though see inflate()) */ - -#define Z_DEFLATED 8 -/* The deflate compression method (the only one supported in this version) */ - -#define Z_NULL 0 /* for initializing zalloc, zfree, opaque */ - -#define zlib_version zlibVersion() -/* for compatibility with versions < 1.0.2 */ - - /* basic functions */ - -ZEXTERN const char * ZEXPORT zlibVersion OF((void)); -/* The application can compare zlibVersion and ZLIB_VERSION for consistency. - If the first character differs, the library code actually used is - not compatible with the zlib.h header file used by the application. - This check is automatically made by deflateInit and inflateInit. - */ - -/* -ZEXTERN int ZEXPORT deflateInit OF((z_streamp strm, int level)); - - Initializes the internal stream state for compression. The fields - zalloc, zfree and opaque must be initialized before by the caller. - If zalloc and zfree are set to Z_NULL, deflateInit updates them to - use default allocation functions. - - The compression level must be Z_DEFAULT_COMPRESSION, or between 0 and 9: - 1 gives best speed, 9 gives best compression, 0 gives no compression at - all (the input data is simply copied a block at a time). - Z_DEFAULT_COMPRESSION requests a default compromise between speed and - compression (currently equivalent to level 6). - - deflateInit returns Z_OK if success, Z_MEM_ERROR if there was not - enough memory, Z_STREAM_ERROR if level is not a valid compression level, - Z_VERSION_ERROR if the zlib library version (zlib_version) is incompatible - with the version assumed by the caller (ZLIB_VERSION). - msg is set to null if there is no error message. deflateInit does not - perform any compression: this will be done by deflate(). -*/ - - -ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); -/* - deflate compresses as much data as possible, and stops when the input - buffer becomes empty or the output buffer becomes full. It may introduce some - output latency (reading input without producing any output) except when - forced to flush. - - The detailed semantics are as follows. deflate performs one or both of the - following actions: - - - Compress more input starting at next_in and update next_in and avail_in - accordingly. If not all input can be processed (because there is not - enough room in the output buffer), next_in and avail_in are updated and - processing will resume at this point for the next call of deflate(). - - - Provide more output starting at next_out and update next_out and avail_out - accordingly. This action is forced if the parameter flush is non zero. - Forcing flush frequently degrades the compression ratio, so this parameter - should be set only when necessary (in interactive applications). - Some output may be provided even if flush is not set. - - Before the call of deflate(), the application should ensure that at least - one of the actions is possible, by providing more input and/or consuming - more output, and updating avail_in or avail_out accordingly; avail_out - should never be zero before the call. The application can consume the - compressed output when it wants, for example when the output buffer is full - (avail_out == 0), or after each call of deflate(). If deflate returns Z_OK - and with zero avail_out, it must be called again after making room in the - output buffer because there might be more output pending. - - Normally the parameter flush is set to Z_NO_FLUSH, which allows deflate to - decide how much data to accumualte before producing output, in order to - maximize compression. - - If the parameter flush is set to Z_SYNC_FLUSH, all pending output is - flushed to the output buffer and the output is aligned on a byte boundary, so - that the decompressor can get all input data available so far. (In particular - avail_in is zero after the call if enough output space has been provided - before the call.) Flushing may degrade compression for some compression - algorithms and so it should be used only when necessary. - - If flush is set to Z_FULL_FLUSH, all output is flushed as with - Z_SYNC_FLUSH, and the compression state is reset so that decompression can - restart from this point if previous compressed data has been damaged or if - random access is desired. Using Z_FULL_FLUSH too often can seriously degrade - compression. - - If deflate returns with avail_out == 0, this function must be called again - with the same value of the flush parameter and more output space (updated - avail_out), until the flush is complete (deflate returns with non-zero - avail_out). In the case of a Z_FULL_FLUSH or Z_SYNC_FLUSH, make sure that - avail_out is greater than six to avoid repeated flush markers due to - avail_out == 0 on return. - - If the parameter flush is set to Z_FINISH, pending input is processed, - pending output is flushed and deflate returns with Z_STREAM_END if there - was enough output space; if deflate returns with Z_OK, this function must be - called again with Z_FINISH and more output space (updated avail_out) but no - more input data, until it returns with Z_STREAM_END or an error. After - deflate has returned Z_STREAM_END, the only possible operations on the - stream are deflateReset or deflateEnd. - - Z_FINISH can be used immediately after deflateInit if all the compression - is to be done in a single step. In this case, avail_out must be at least - the value returned by deflateBound (see below). If deflate does not return - Z_STREAM_END, then it must be called again as described above. - - deflate() sets strm->adler to the adler32 checksum of all input read - so far (that is, total_in bytes). - - deflate() may update strm->data_type if it can make a good guess about - the input data type (Z_BINARY or Z_TEXT). In doubt, the data is considered - binary. This field is only for information purposes and does not affect - the compression algorithm in any manner. - - deflate() returns Z_OK if some progress has been made (more input - processed or more output produced), Z_STREAM_END if all input has been - consumed and all output has been produced (only when flush is set to - Z_FINISH), Z_STREAM_ERROR if the stream state was inconsistent (for example - if next_in or next_out was NULL), Z_BUF_ERROR if no progress is possible - (for example avail_in or avail_out was zero). Note that Z_BUF_ERROR is not - fatal, and deflate() can be called again with more input and more output - space to continue compressing. -*/ - - -ZEXTERN int ZEXPORT deflateEnd OF((z_streamp strm)); -/* - All dynamically allocated data structures for this stream are freed. - This function discards any unprocessed input and does not flush any - pending output. - - deflateEnd returns Z_OK if success, Z_STREAM_ERROR if the - stream state was inconsistent, Z_DATA_ERROR if the stream was freed - prematurely (some input or output was discarded). In the error case, - msg may be set but then points to a static string (which must not be - deallocated). -*/ - - -/* -ZEXTERN int ZEXPORT inflateInit OF((z_streamp strm)); - - Initializes the internal stream state for decompression. The fields - next_in, avail_in, zalloc, zfree and opaque must be initialized before by - the caller. If next_in is not Z_NULL and avail_in is large enough (the exact - value depends on the compression method), inflateInit determines the - compression method from the zlib header and allocates all data structures - accordingly; otherwise the allocation will be deferred to the first call of - inflate. If zalloc and zfree are set to Z_NULL, inflateInit updates them to - use default allocation functions. - - inflateInit returns Z_OK if success, Z_MEM_ERROR if there was not enough - memory, Z_VERSION_ERROR if the zlib library version is incompatible with the - version assumed by the caller. msg is set to null if there is no error - message. inflateInit does not perform any decompression apart from reading - the zlib header if present: this will be done by inflate(). (So next_in and - avail_in may be modified, but next_out and avail_out are unchanged.) -*/ - - -ZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush)); -/* - inflate decompresses as much data as possible, and stops when the input - buffer becomes empty or the output buffer becomes full. It may introduce - some output latency (reading input without producing any output) except when - forced to flush. - - The detailed semantics are as follows. inflate performs one or both of the - following actions: - - - Decompress more input starting at next_in and update next_in and avail_in - accordingly. If not all input can be processed (because there is not - enough room in the output buffer), next_in is updated and processing - will resume at this point for the next call of inflate(). - - - Provide more output starting at next_out and update next_out and avail_out - accordingly. inflate() provides as much output as possible, until there - is no more input data or no more space in the output buffer (see below - about the flush parameter). - - Before the call of inflate(), the application should ensure that at least - one of the actions is possible, by providing more input and/or consuming - more output, and updating the next_* and avail_* values accordingly. - The application can consume the uncompressed output when it wants, for - example when the output buffer is full (avail_out == 0), or after each - call of inflate(). If inflate returns Z_OK and with zero avail_out, it - must be called again after making room in the output buffer because there - might be more output pending. - - The flush parameter of inflate() can be Z_NO_FLUSH, Z_SYNC_FLUSH, - Z_FINISH, or Z_BLOCK. Z_SYNC_FLUSH requests that inflate() flush as much - output as possible to the output buffer. Z_BLOCK requests that inflate() stop - if and when it gets to the next deflate block boundary. When decoding the - zlib or gzip format, this will cause inflate() to return immediately after - the header and before the first block. When doing a raw inflate, inflate() - will go ahead and process the first block, and will return when it gets to - the end of that block, or when it runs out of data. - - The Z_BLOCK option assists in appending to or combining deflate streams. - Also to assist in this, on return inflate() will set strm->data_type to the - number of unused bits in the last byte taken from strm->next_in, plus 64 - if inflate() is currently decoding the last block in the deflate stream, - plus 128 if inflate() returned immediately after decoding an end-of-block - code or decoding the complete header up to just before the first byte of the - deflate stream. The end-of-block will not be indicated until all of the - uncompressed data from that block has been written to strm->next_out. The - number of unused bits may in general be greater than seven, except when - bit 7 of data_type is set, in which case the number of unused bits will be - less than eight. - - inflate() should normally be called until it returns Z_STREAM_END or an - error. However if all decompression is to be performed in a single step - (a single call of inflate), the parameter flush should be set to - Z_FINISH. In this case all pending input is processed and all pending - output is flushed; avail_out must be large enough to hold all the - uncompressed data. (The size of the uncompressed data may have been saved - by the compressor for this purpose.) The next operation on this stream must - be inflateEnd to deallocate the decompression state. The use of Z_FINISH - is never required, but can be used to inform inflate that a faster approach - may be used for the single inflate() call. - - In this implementation, inflate() always flushes as much output as - possible to the output buffer, and always uses the faster approach on the - first call. So the only effect of the flush parameter in this implementation - is on the return value of inflate(), as noted below, or when it returns early - because Z_BLOCK is used. - - If a preset dictionary is needed after this call (see inflateSetDictionary - below), inflate sets strm->adler to the adler32 checksum of the dictionary - chosen by the compressor and returns Z_NEED_DICT; otherwise it sets - strm->adler to the adler32 checksum of all output produced so far (that is, - total_out bytes) and returns Z_OK, Z_STREAM_END or an error code as described - below. At the end of the stream, inflate() checks that its computed adler32 - checksum is equal to that saved by the compressor and returns Z_STREAM_END - only if the checksum is correct. - - inflate() will decompress and check either zlib-wrapped or gzip-wrapped - deflate data. The header type is detected automatically. Any information - contained in the gzip header is not retained, so applications that need that - information should instead use raw inflate, see inflateInit2() below, or - inflateBack() and perform their own processing of the gzip header and - trailer. - - inflate() returns Z_OK if some progress has been made (more input processed - or more output produced), Z_STREAM_END if the end of the compressed data has - been reached and all uncompressed output has been produced, Z_NEED_DICT if a - preset dictionary is needed at this point, Z_DATA_ERROR if the input data was - corrupted (input stream not conforming to the zlib format or incorrect check - value), Z_STREAM_ERROR if the stream structure was inconsistent (for example - if next_in or next_out was NULL), Z_MEM_ERROR if there was not enough memory, - Z_BUF_ERROR if no progress is possible or if there was not enough room in the - output buffer when Z_FINISH is used. Note that Z_BUF_ERROR is not fatal, and - inflate() can be called again with more input and more output space to - continue decompressing. If Z_DATA_ERROR is returned, the application may then - call inflateSync() to look for a good compression block if a partial recovery - of the data is desired. -*/ - - -ZEXTERN int ZEXPORT inflateEnd OF((z_streamp strm)); -/* - All dynamically allocated data structures for this stream are freed. - This function discards any unprocessed input and does not flush any - pending output. - - inflateEnd returns Z_OK if success, Z_STREAM_ERROR if the stream state - was inconsistent. In the error case, msg may be set but then points to a - static string (which must not be deallocated). -*/ - - /* Advanced functions */ - -/* - The following functions are needed only in some special applications. -*/ - -/* -ZEXTERN int ZEXPORT deflateInit2 OF((z_streamp strm, - int level, - int method, - int windowBits, - int memLevel, - int strategy)); - - This is another version of deflateInit with more compression options. The - fields next_in, zalloc, zfree and opaque must be initialized before by - the caller. - - The method parameter is the compression method. It must be Z_DEFLATED in - this version of the library. - - The windowBits parameter is the base two logarithm of the window size - (the size of the history buffer). It should be in the range 8..15 for this - version of the library. Larger values of this parameter result in better - compression at the expense of memory usage. The default value is 15 if - deflateInit is used instead. - - windowBits can also be -8..-15 for raw deflate. In this case, -windowBits - determines the window size. deflate() will then generate raw deflate data - with no zlib header or trailer, and will not compute an adler32 check value. - - windowBits can also be greater than 15 for optional gzip encoding. Add - 16 to windowBits to write a simple gzip header and trailer around the - compressed data instead of a zlib wrapper. The gzip header will have no - file name, no extra data, no comment, no modification time (set to zero), - no header crc, and the operating system will be set to 255 (unknown). If a - gzip stream is being written, strm->adler is a crc32 instead of an adler32. - - The memLevel parameter specifies how much memory should be allocated - for the internal compression state. memLevel=1 uses minimum memory but - is slow and reduces compression ratio; memLevel=9 uses maximum memory - for optimal speed. The default value is 8. See zconf.h for total memory - usage as a function of windowBits and memLevel. - - The strategy parameter is used to tune the compression algorithm. Use the - value Z_DEFAULT_STRATEGY for normal data, Z_FILTERED for data produced by a - filter (or predictor), Z_HUFFMAN_ONLY to force Huffman encoding only (no - string match), or Z_RLE to limit match distances to one (run-length - encoding). Filtered data consists mostly of small values with a somewhat - random distribution. In this case, the compression algorithm is tuned to - compress them better. The effect of Z_FILTERED is to force more Huffman - coding and less string matching; it is somewhat intermediate between - Z_DEFAULT and Z_HUFFMAN_ONLY. Z_RLE is designed to be almost as fast as - Z_HUFFMAN_ONLY, but give better compression for PNG image data. The strategy - parameter only affects the compression ratio but not the correctness of the - compressed output even if it is not set appropriately. Z_FIXED prevents the - use of dynamic Huffman codes, allowing for a simpler decoder for special - applications. - - deflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough - memory, Z_STREAM_ERROR if a parameter is invalid (such as an invalid - method). msg is set to null if there is no error message. deflateInit2 does - not perform any compression: this will be done by deflate(). -*/ - -ZEXTERN int ZEXPORT deflateSetDictionary OF((z_streamp strm, - const Bytef *dictionary, - uInt dictLength)); -/* - Initializes the compression dictionary from the given byte sequence - without producing any compressed output. This function must be called - immediately after deflateInit, deflateInit2 or deflateReset, before any - call of deflate. The compressor and decompressor must use exactly the same - dictionary (see inflateSetDictionary). - - The dictionary should consist of strings (byte sequences) that are likely - to be encountered later in the data to be compressed, with the most commonly - used strings preferably put towards the end of the dictionary. Using a - dictionary is most useful when the data to be compressed is short and can be - predicted with good accuracy; the data can then be compressed better than - with the default empty dictionary. - - Depending on the size of the compression data structures selected by - deflateInit or deflateInit2, a part of the dictionary may in effect be - discarded, for example if the dictionary is larger than the window size in - deflate or deflate2. Thus the strings most likely to be useful should be - put at the end of the dictionary, not at the front. In addition, the - current implementation of deflate will use at most the window size minus - 262 bytes of the provided dictionary. - - Upon return of this function, strm->adler is set to the adler32 value - of the dictionary; the decompressor may later use this value to determine - which dictionary has been used by the compressor. (The adler32 value - applies to the whole dictionary even if only a subset of the dictionary is - actually used by the compressor.) If a raw deflate was requested, then the - adler32 value is not computed and strm->adler is not set. - - deflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a - parameter is invalid (such as NULL dictionary) or the stream state is - inconsistent (for example if deflate has already been called for this stream - or if the compression method is bsort). deflateSetDictionary does not - perform any compression: this will be done by deflate(). -*/ - -ZEXTERN int ZEXPORT deflateCopy OF((z_streamp dest, - z_streamp source)); -/* - Sets the destination stream as a complete copy of the source stream. - - This function can be useful when several compression strategies will be - tried, for example when there are several ways of pre-processing the input - data with a filter. The streams that will be discarded should then be freed - by calling deflateEnd. Note that deflateCopy duplicates the internal - compression state which can be quite large, so this strategy is slow and - can consume lots of memory. - - deflateCopy returns Z_OK if success, Z_MEM_ERROR if there was not - enough memory, Z_STREAM_ERROR if the source stream state was inconsistent - (such as zalloc being NULL). msg is left unchanged in both source and - destination. -*/ - -ZEXTERN int ZEXPORT deflateReset OF((z_streamp strm)); -/* - This function is equivalent to deflateEnd followed by deflateInit, - but does not free and reallocate all the internal compression state. - The stream will keep the same compression level and any other attributes - that may have been set by deflateInit2. - - deflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source - stream state was inconsistent (such as zalloc or state being NULL). -*/ - -ZEXTERN int ZEXPORT deflateParams OF((z_streamp strm, - int level, - int strategy)); -/* - Dynamically update the compression level and compression strategy. The - interpretation of level and strategy is as in deflateInit2. This can be - used to switch between compression and straight copy of the input data, or - to switch to a different kind of input data requiring a different - strategy. If the compression level is changed, the input available so far - is compressed with the old level (and may be flushed); the new level will - take effect only at the next call of deflate(). - - Before the call of deflateParams, the stream state must be set as for - a call of deflate(), since the currently available input may have to - be compressed and flushed. In particular, strm->avail_out must be non-zero. - - deflateParams returns Z_OK if success, Z_STREAM_ERROR if the source - stream state was inconsistent or if a parameter was invalid, Z_BUF_ERROR - if strm->avail_out was zero. -*/ - -ZEXTERN int ZEXPORT deflateTune OF((z_streamp strm, - int good_length, - int max_lazy, - int nice_length, - int max_chain)); -/* - Fine tune deflate's internal compression parameters. This should only be - used by someone who understands the algorithm used by zlib's deflate for - searching for the best matching string, and even then only by the most - fanatic optimizer trying to squeeze out the last compressed bit for their - specific input data. Read the deflate.c source code for the meaning of the - max_lazy, good_length, nice_length, and max_chain parameters. - - deflateTune() can be called after deflateInit() or deflateInit2(), and - returns Z_OK on success, or Z_STREAM_ERROR for an invalid deflate stream. - */ - -ZEXTERN uLong ZEXPORT deflateBound OF((z_streamp strm, - uLong sourceLen)); -/* - deflateBound() returns an upper bound on the compressed size after - deflation of sourceLen bytes. It must be called after deflateInit() - or deflateInit2(). This would be used to allocate an output buffer - for deflation in a single pass, and so would be called before deflate(). -*/ - -ZEXTERN int ZEXPORT deflatePrime OF((z_streamp strm, - int bits, - int value)); -/* - deflatePrime() inserts bits in the deflate output stream. The intent - is that this function is used to start off the deflate output with the - bits leftover from a previous deflate stream when appending to it. As such, - this function can only be used for raw deflate, and must be used before the - first deflate() call after a deflateInit2() or deflateReset(). bits must be - less than or equal to 16, and that many of the least significant bits of - value will be inserted in the output. - - deflatePrime returns Z_OK if success, or Z_STREAM_ERROR if the source - stream state was inconsistent. -*/ - -ZEXTERN int ZEXPORT deflateSetHeader OF((z_streamp strm, - gz_headerp head)); -/* - deflateSetHeader() provides gzip header information for when a gzip - stream is requested by deflateInit2(). deflateSetHeader() may be called - after deflateInit2() or deflateReset() and before the first call of - deflate(). The text, time, os, extra field, name, and comment information - in the provided gz_header structure are written to the gzip header (xflag is - ignored -- the extra flags are set according to the compression level). The - caller must assure that, if not Z_NULL, name and comment are terminated with - a zero byte, and that if extra is not Z_NULL, that extra_len bytes are - available there. If hcrc is true, a gzip header crc is included. Note that - the current versions of the command-line version of gzip (up through version - 1.3.x) do not support header crc's, and will report that it is a "multi-part - gzip file" and give up. - - If deflateSetHeader is not used, the default gzip header has text false, - the time set to zero, and os set to 255, with no extra, name, or comment - fields. The gzip header is returned to the default state by deflateReset(). - - deflateSetHeader returns Z_OK if success, or Z_STREAM_ERROR if the source - stream state was inconsistent. -*/ - -/* -ZEXTERN int ZEXPORT inflateInit2 OF((z_streamp strm, - int windowBits)); - - This is another version of inflateInit with an extra parameter. The - fields next_in, avail_in, zalloc, zfree and opaque must be initialized - before by the caller. - - The windowBits parameter is the base two logarithm of the maximum window - size (the size of the history buffer). It should be in the range 8..15 for - this version of the library. The default value is 15 if inflateInit is used - instead. windowBits must be greater than or equal to the windowBits value - provided to deflateInit2() while compressing, or it must be equal to 15 if - deflateInit2() was not used. If a compressed stream with a larger window - size is given as input, inflate() will return with the error code - Z_DATA_ERROR instead of trying to allocate a larger window. - - windowBits can also be -8..-15 for raw inflate. In this case, -windowBits - determines the window size. inflate() will then process raw deflate data, - not looking for a zlib or gzip header, not generating a check value, and not - looking for any check values for comparison at the end of the stream. This - is for use with other formats that use the deflate compressed data format - such as zip. Those formats provide their own check values. If a custom - format is developed using the raw deflate format for compressed data, it is - recommended that a check value such as an adler32 or a crc32 be applied to - the uncompressed data as is done in the zlib, gzip, and zip formats. For - most applications, the zlib format should be used as is. Note that comments - above on the use in deflateInit2() applies to the magnitude of windowBits. - - windowBits can also be greater than 15 for optional gzip decoding. Add - 32 to windowBits to enable zlib and gzip decoding with automatic header - detection, or add 16 to decode only the gzip format (the zlib format will - return a Z_DATA_ERROR). If a gzip stream is being decoded, strm->adler is - a crc32 instead of an adler32. - - inflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough - memory, Z_STREAM_ERROR if a parameter is invalid (such as a null strm). msg - is set to null if there is no error message. inflateInit2 does not perform - any decompression apart from reading the zlib header if present: this will - be done by inflate(). (So next_in and avail_in may be modified, but next_out - and avail_out are unchanged.) -*/ - -ZEXTERN int ZEXPORT inflateSetDictionary OF((z_streamp strm, - const Bytef *dictionary, - uInt dictLength)); -/* - Initializes the decompression dictionary from the given uncompressed byte - sequence. This function must be called immediately after a call of inflate, - if that call returned Z_NEED_DICT. The dictionary chosen by the compressor - can be determined from the adler32 value returned by that call of inflate. - The compressor and decompressor must use exactly the same dictionary (see - deflateSetDictionary). For raw inflate, this function can be called - immediately after inflateInit2() or inflateReset() and before any call of - inflate() to set the dictionary. The application must insure that the - dictionary that was used for compression is provided. - - inflateSetDictionary returns Z_OK if success, Z_STREAM_ERROR if a - parameter is invalid (such as NULL dictionary) or the stream state is - inconsistent, Z_DATA_ERROR if the given dictionary doesn't match the - expected one (incorrect adler32 value). inflateSetDictionary does not - perform any decompression: this will be done by subsequent calls of - inflate(). -*/ - -ZEXTERN int ZEXPORT inflateSync OF((z_streamp strm)); -/* - Skips invalid compressed data until a full flush point (see above the - description of deflate with Z_FULL_FLUSH) can be found, or until all - available input is skipped. No output is provided. - - inflateSync returns Z_OK if a full flush point has been found, Z_BUF_ERROR - if no more input was provided, Z_DATA_ERROR if no flush point has been found, - or Z_STREAM_ERROR if the stream structure was inconsistent. In the success - case, the application may save the current current value of total_in which - indicates where valid compressed data was found. In the error case, the - application may repeatedly call inflateSync, providing more input each time, - until success or end of the input data. -*/ - -ZEXTERN int ZEXPORT inflateCopy OF((z_streamp dest, - z_streamp source)); -/* - Sets the destination stream as a complete copy of the source stream. - - This function can be useful when randomly accessing a large stream. The - first pass through the stream can periodically record the inflate state, - allowing restarting inflate at those points when randomly accessing the - stream. - - inflateCopy returns Z_OK if success, Z_MEM_ERROR if there was not - enough memory, Z_STREAM_ERROR if the source stream state was inconsistent - (such as zalloc being NULL). msg is left unchanged in both source and - destination. -*/ - -ZEXTERN int ZEXPORT inflateReset OF((z_streamp strm)); -/* - This function is equivalent to inflateEnd followed by inflateInit, - but does not free and reallocate all the internal decompression state. - The stream will keep attributes that may have been set by inflateInit2. - - inflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source - stream state was inconsistent (such as zalloc or state being NULL). -*/ - -ZEXTERN int ZEXPORT inflatePrime OF((z_streamp strm, - int bits, - int value)); -/* - This function inserts bits in the inflate input stream. The intent is - that this function is used to start inflating at a bit position in the - middle of a byte. The provided bits will be used before any bytes are used - from next_in. This function should only be used with raw inflate, and - should be used before the first inflate() call after inflateInit2() or - inflateReset(). bits must be less than or equal to 16, and that many of the - least significant bits of value will be inserted in the input. - - inflatePrime returns Z_OK if success, or Z_STREAM_ERROR if the source - stream state was inconsistent. -*/ - -ZEXTERN int ZEXPORT inflateGetHeader OF((z_streamp strm, - gz_headerp head)); -/* - inflateGetHeader() requests that gzip header information be stored in the - provided gz_header structure. inflateGetHeader() may be called after - inflateInit2() or inflateReset(), and before the first call of inflate(). - As inflate() processes the gzip stream, head->done is zero until the header - is completed, at which time head->done is set to one. If a zlib stream is - being decoded, then head->done is set to -1 to indicate that there will be - no gzip header information forthcoming. Note that Z_BLOCK can be used to - force inflate() to return immediately after header processing is complete - and before any actual data is decompressed. - - The text, time, xflags, and os fields are filled in with the gzip header - contents. hcrc is set to true if there is a header CRC. (The header CRC - was valid if done is set to one.) If extra is not Z_NULL, then extra_max - contains the maximum number of bytes to write to extra. Once done is true, - extra_len contains the actual extra field length, and extra contains the - extra field, or that field truncated if extra_max is less than extra_len. - If name is not Z_NULL, then up to name_max characters are written there, - terminated with a zero unless the length is greater than name_max. If - comment is not Z_NULL, then up to comm_max characters are written there, - terminated with a zero unless the length is greater than comm_max. When - any of extra, name, or comment are not Z_NULL and the respective field is - not present in the header, then that field is set to Z_NULL to signal its - absence. This allows the use of deflateSetHeader() with the returned - structure to duplicate the header. However if those fields are set to - allocated memory, then the application will need to save those pointers - elsewhere so that they can be eventually freed. - - If inflateGetHeader is not used, then the header information is simply - discarded. The header is always checked for validity, including the header - CRC if present. inflateReset() will reset the process to discard the header - information. The application would need to call inflateGetHeader() again to - retrieve the header from the next gzip stream. - - inflateGetHeader returns Z_OK if success, or Z_STREAM_ERROR if the source - stream state was inconsistent. -*/ - -/* -ZEXTERN int ZEXPORT inflateBackInit OF((z_streamp strm, int windowBits, - unsigned char FAR *window)); - - Initialize the internal stream state for decompression using inflateBack() - calls. The fields zalloc, zfree and opaque in strm must be initialized - before the call. If zalloc and zfree are Z_NULL, then the default library- - derived memory allocation routines are used. windowBits is the base two - logarithm of the window size, in the range 8..15. window is a caller - supplied buffer of that size. Except for special applications where it is - assured that deflate was used with small window sizes, windowBits must be 15 - and a 32K byte window must be supplied to be able to decompress general - deflate streams. - - See inflateBack() for the usage of these routines. - - inflateBackInit will return Z_OK on success, Z_STREAM_ERROR if any of - the paramaters are invalid, Z_MEM_ERROR if the internal state could not - be allocated, or Z_VERSION_ERROR if the version of the library does not - match the version of the header file. -*/ - -typedef unsigned (*in_func) OF((void FAR *, unsigned char FAR * FAR *)); -typedef int (*out_func) OF((void FAR *, unsigned char FAR *, unsigned)); - -ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, - in_func in, void FAR *in_desc, - out_func out, void FAR *out_desc)); -/* - inflateBack() does a raw inflate with a single call using a call-back - interface for input and output. This is more efficient than inflate() for - file i/o applications in that it avoids copying between the output and the - sliding window by simply making the window itself the output buffer. This - function trusts the application to not change the output buffer passed by - the output function, at least until inflateBack() returns. - - inflateBackInit() must be called first to allocate the internal state - and to initialize the state with the user-provided window buffer. - inflateBack() may then be used multiple times to inflate a complete, raw - deflate stream with each call. inflateBackEnd() is then called to free - the allocated state. - - A raw deflate stream is one with no zlib or gzip header or trailer. - This routine would normally be used in a utility that reads zip or gzip - files and writes out uncompressed files. The utility would decode the - header and process the trailer on its own, hence this routine expects - only the raw deflate stream to decompress. This is different from the - normal behavior of inflate(), which expects either a zlib or gzip header and - trailer around the deflate stream. - - inflateBack() uses two subroutines supplied by the caller that are then - called by inflateBack() for input and output. inflateBack() calls those - routines until it reads a complete deflate stream and writes out all of the - uncompressed data, or until it encounters an error. The function's - parameters and return types are defined above in the in_func and out_func - typedefs. inflateBack() will call in(in_desc, &buf) which should return the - number of bytes of provided input, and a pointer to that input in buf. If - there is no input available, in() must return zero--buf is ignored in that - case--and inflateBack() will return a buffer error. inflateBack() will call - out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. out() - should return zero on success, or non-zero on failure. If out() returns - non-zero, inflateBack() will return with an error. Neither in() nor out() - are permitted to change the contents of the window provided to - inflateBackInit(), which is also the buffer that out() uses to write from. - The length written by out() will be at most the window size. Any non-zero - amount of input may be provided by in(). - - For convenience, inflateBack() can be provided input on the first call by - setting strm->next_in and strm->avail_in. If that input is exhausted, then - in() will be called. Therefore strm->next_in must be initialized before - calling inflateBack(). If strm->next_in is Z_NULL, then in() will be called - immediately for input. If strm->next_in is not Z_NULL, then strm->avail_in - must also be initialized, and then if strm->avail_in is not zero, input will - initially be taken from strm->next_in[0 .. strm->avail_in - 1]. - - The in_desc and out_desc parameters of inflateBack() is passed as the - first parameter of in() and out() respectively when they are called. These - descriptors can be optionally used to pass any information that the caller- - supplied in() and out() functions need to do their job. - - On return, inflateBack() will set strm->next_in and strm->avail_in to - pass back any unused input that was provided by the last in() call. The - return values of inflateBack() can be Z_STREAM_END on success, Z_BUF_ERROR - if in() or out() returned an error, Z_DATA_ERROR if there was a format - error in the deflate stream (in which case strm->msg is set to indicate the - nature of the error), or Z_STREAM_ERROR if the stream was not properly - initialized. In the case of Z_BUF_ERROR, an input or output error can be - distinguished using strm->next_in which will be Z_NULL only if in() returned - an error. If strm->next is not Z_NULL, then the Z_BUF_ERROR was due to - out() returning non-zero. (in() will always be called before out(), so - strm->next_in is assured to be defined if out() returns non-zero.) Note - that inflateBack() cannot return Z_OK. -*/ - -ZEXTERN int ZEXPORT inflateBackEnd OF((z_streamp strm)); -/* - All memory allocated by inflateBackInit() is freed. - - inflateBackEnd() returns Z_OK on success, or Z_STREAM_ERROR if the stream - state was inconsistent. -*/ - -ZEXTERN uLong ZEXPORT zlibCompileFlags OF((void)); -/* Return flags indicating compile-time options. - - Type sizes, two bits each, 00 = 16 bits, 01 = 32, 10 = 64, 11 = other: - 1.0: size of uInt - 3.2: size of uLong - 5.4: size of voidpf (pointer) - 7.6: size of z_off_t - - Compiler, assembler, and debug options: - 8: DEBUG - 9: ASMV or ASMINF -- use ASM code - 10: ZLIB_WINAPI -- exported functions use the WINAPI calling convention - 11: 0 (reserved) - - One-time table building (smaller code, but not thread-safe if true): - 12: BUILDFIXED -- build static block decoding tables when needed - 13: DYNAMIC_CRC_TABLE -- build CRC calculation tables when needed - 14,15: 0 (reserved) - - Library content (indicates missing functionality): - 16: NO_GZCOMPRESS -- gz* functions cannot compress (to avoid linking - deflate code when not needed) - 17: NO_GZIP -- deflate can't write gzip streams, and inflate can't detect - and decode gzip streams (to avoid linking crc code) - 18-19: 0 (reserved) - - Operation variations (changes in library functionality): - 20: PKZIP_BUG_WORKAROUND -- slightly more permissive inflate - 21: FASTEST -- deflate algorithm with only one, lowest compression level - 22,23: 0 (reserved) - - The sprintf variant used by gzprintf (zero is best): - 24: 0 = vs*, 1 = s* -- 1 means limited to 20 arguments after the format - 25: 0 = *nprintf, 1 = *printf -- 1 means gzprintf() not secure! - 26: 0 = returns value, 1 = void -- 1 means inferred string length returned - - Remainder: - 27-31: 0 (reserved) - */ - - - /* utility functions */ - -/* - The following utility functions are implemented on top of the - basic stream-oriented functions. To simplify the interface, some - default options are assumed (compression level and memory usage, - standard memory allocation functions). The source code of these - utility functions can easily be modified if you need special options. -*/ - -ZEXTERN int ZEXPORT compress OF((Bytef *dest, uLongf *destLen, - const Bytef *source, uLong sourceLen)); -/* - Compresses the source buffer into the destination buffer. sourceLen is - the byte length of the source buffer. Upon entry, destLen is the total - size of the destination buffer, which must be at least the value returned - by compressBound(sourceLen). Upon exit, destLen is the actual size of the - compressed buffer. - This function can be used to compress a whole file at once if the - input file is mmap'ed. - compress returns Z_OK if success, Z_MEM_ERROR if there was not - enough memory, Z_BUF_ERROR if there was not enough room in the output - buffer. -*/ - -ZEXTERN int ZEXPORT compress2 OF((Bytef *dest, uLongf *destLen, - const Bytef *source, uLong sourceLen, - int level)); -/* - Compresses the source buffer into the destination buffer. The level - parameter has the same meaning as in deflateInit. sourceLen is the byte - length of the source buffer. Upon entry, destLen is the total size of the - destination buffer, which must be at least the value returned by - compressBound(sourceLen). Upon exit, destLen is the actual size of the - compressed buffer. - - compress2 returns Z_OK if success, Z_MEM_ERROR if there was not enough - memory, Z_BUF_ERROR if there was not enough room in the output buffer, - Z_STREAM_ERROR if the level parameter is invalid. -*/ - -ZEXTERN uLong ZEXPORT compressBound OF((uLong sourceLen)); -/* - compressBound() returns an upper bound on the compressed size after - compress() or compress2() on sourceLen bytes. It would be used before - a compress() or compress2() call to allocate the destination buffer. -*/ - -ZEXTERN int ZEXPORT uncompress OF((Bytef *dest, uLongf *destLen, - const Bytef *source, uLong sourceLen)); -/* - Decompresses the source buffer into the destination buffer. sourceLen is - the byte length of the source buffer. Upon entry, destLen is the total - size of the destination buffer, which must be large enough to hold the - entire uncompressed data. (The size of the uncompressed data must have - been saved previously by the compressor and transmitted to the decompressor - by some mechanism outside the scope of this compression library.) - Upon exit, destLen is the actual size of the compressed buffer. - This function can be used to decompress a whole file at once if the - input file is mmap'ed. - - uncompress returns Z_OK if success, Z_MEM_ERROR if there was not - enough memory, Z_BUF_ERROR if there was not enough room in the output - buffer, or Z_DATA_ERROR if the input data was corrupted or incomplete. -*/ - - -typedef voidp gzFile; - -ZEXTERN gzFile ZEXPORT gzopen OF((const char *path, const char *mode)); -/* - Opens a gzip (.gz) file for reading or writing. The mode parameter - is as in fopen ("rb" or "wb") but can also include a compression level - ("wb9") or a strategy: 'f' for filtered data as in "wb6f", 'h' for - Huffman only compression as in "wb1h", or 'R' for run-length encoding - as in "wb1R". (See the description of deflateInit2 for more information - about the strategy parameter.) - - gzopen can be used to read a file which is not in gzip format; in this - case gzread will directly read from the file without decompression. - - gzopen returns NULL if the file could not be opened or if there was - insufficient memory to allocate the (de)compression state; errno - can be checked to distinguish the two cases (if errno is zero, the - zlib error is Z_MEM_ERROR). */ - -ZEXTERN gzFile ZEXPORT gzdopen OF((int fd, const char *mode)); -/* - gzdopen() associates a gzFile with the file descriptor fd. File - descriptors are obtained from calls like open, dup, creat, pipe or - fileno (in the file has been previously opened with fopen). - The mode parameter is as in gzopen. - The next call of gzclose on the returned gzFile will also close the - file descriptor fd, just like fclose(fdopen(fd), mode) closes the file - descriptor fd. If you want to keep fd open, use gzdopen(dup(fd), mode). - gzdopen returns NULL if there was insufficient memory to allocate - the (de)compression state. -*/ - -ZEXTERN int ZEXPORT gzsetparams OF((gzFile file, int level, int strategy)); -/* - Dynamically update the compression level or strategy. See the description - of deflateInit2 for the meaning of these parameters. - gzsetparams returns Z_OK if success, or Z_STREAM_ERROR if the file was not - opened for writing. -*/ - -ZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len)); -/* - Reads the given number of uncompressed bytes from the compressed file. - If the input file was not in gzip format, gzread copies the given number - of bytes into the buffer. - gzread returns the number of uncompressed bytes actually read (0 for - end of file, -1 for error). */ - -ZEXTERN int ZEXPORT gzwrite OF((gzFile file, - voidpc buf, unsigned len)); -/* - Writes the given number of uncompressed bytes into the compressed file. - gzwrite returns the number of uncompressed bytes actually written - (0 in case of error). -*/ - -ZEXTERN int ZEXPORTVA gzprintf OF((gzFile file, const char *format, ...)); -/* - Converts, formats, and writes the args to the compressed file under - control of the format string, as in fprintf. gzprintf returns the number of - uncompressed bytes actually written (0 in case of error). The number of - uncompressed bytes written is limited to 4095. The caller should assure that - this limit is not exceeded. If it is exceeded, then gzprintf() will return - return an error (0) with nothing written. In this case, there may also be a - buffer overflow with unpredictable consequences, which is possible only if - zlib was compiled with the insecure functions sprintf() or vsprintf() - because the secure snprintf() or vsnprintf() functions were not available. -*/ - -ZEXTERN int ZEXPORT gzputs OF((gzFile file, const char *s)); -/* - Writes the given null-terminated string to the compressed file, excluding - the terminating null character. - gzputs returns the number of characters written, or -1 in case of error. -*/ - -ZEXTERN char * ZEXPORT gzgets OF((gzFile file, char *buf, int len)); -/* - Reads bytes from the compressed file until len-1 characters are read, or - a newline character is read and transferred to buf, or an end-of-file - condition is encountered. The string is then terminated with a null - character. - gzgets returns buf, or Z_NULL in case of error. -*/ - -ZEXTERN int ZEXPORT gzputc OF((gzFile file, int c)); -/* - Writes c, converted to an unsigned char, into the compressed file. - gzputc returns the value that was written, or -1 in case of error. -*/ - -ZEXTERN int ZEXPORT gzgetc OF((gzFile file)); -/* - Reads one byte from the compressed file. gzgetc returns this byte - or -1 in case of end of file or error. -*/ - -ZEXTERN int ZEXPORT gzungetc OF((int c, gzFile file)); -/* - Push one character back onto the stream to be read again later. - Only one character of push-back is allowed. gzungetc() returns the - character pushed, or -1 on failure. gzungetc() will fail if a - character has been pushed but not read yet, or if c is -1. The pushed - character will be discarded if the stream is repositioned with gzseek() - or gzrewind(). -*/ - -ZEXTERN int ZEXPORT gzflush OF((gzFile file, int flush)); -/* - Flushes all pending output into the compressed file. The parameter - flush is as in the deflate() function. The return value is the zlib - error number (see function gzerror below). gzflush returns Z_OK if - the flush parameter is Z_FINISH and all output could be flushed. - gzflush should be called only when strictly necessary because it can - degrade compression. -*/ - -ZEXTERN z_off_t ZEXPORT gzseek OF((gzFile file, - z_off_t offset, int whence)); -/* - Sets the starting position for the next gzread or gzwrite on the - given compressed file. The offset represents a number of bytes in the - uncompressed data stream. The whence parameter is defined as in lseek(2); - the value SEEK_END is not supported. - If the file is opened for reading, this function is emulated but can be - extremely slow. If the file is opened for writing, only forward seeks are - supported; gzseek then compresses a sequence of zeroes up to the new - starting position. - - gzseek returns the resulting offset location as measured in bytes from - the beginning of the uncompressed stream, or -1 in case of error, in - particular if the file is opened for writing and the new starting position - would be before the current position. -*/ - -ZEXTERN int ZEXPORT gzrewind OF((gzFile file)); -/* - Rewinds the given file. This function is supported only for reading. - - gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET) -*/ - -ZEXTERN z_off_t ZEXPORT gztell OF((gzFile file)); -/* - Returns the starting position for the next gzread or gzwrite on the - given compressed file. This position represents a number of bytes in the - uncompressed data stream. - - gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR) -*/ - -ZEXTERN int ZEXPORT gzeof OF((gzFile file)); -/* - Returns 1 when EOF has previously been detected reading the given - input stream, otherwise zero. -*/ - -ZEXTERN int ZEXPORT gzdirect OF((gzFile file)); -/* - Returns 1 if file is being read directly without decompression, otherwise - zero. -*/ - -ZEXTERN int ZEXPORT gzclose OF((gzFile file)); -/* - Flushes all pending output if necessary, closes the compressed file - and deallocates all the (de)compression state. The return value is the zlib - error number (see function gzerror below). -*/ - -ZEXTERN const char * ZEXPORT gzerror OF((gzFile file, int *errnum)); -/* - Returns the error message for the last error which occurred on the - given compressed file. errnum is set to zlib error number. If an - error occurred in the file system and not in the compression library, - errnum is set to Z_ERRNO and the application may consult errno - to get the exact error code. -*/ - -ZEXTERN void ZEXPORT gzclearerr OF((gzFile file)); -/* - Clears the error and end-of-file flags for file. This is analogous to the - clearerr() function in stdio. This is useful for continuing to read a gzip - file that is being written concurrently. -*/ - - /* checksum functions */ - -/* - These functions are not related to compression but are exported - anyway because they might be useful in applications using the - compression library. -*/ - -ZEXTERN uLong ZEXPORT adler32 OF((uLong adler, const Bytef *buf, uInt len)); -/* - Update a running Adler-32 checksum with the bytes buf[0..len-1] and - return the updated checksum. If buf is NULL, this function returns - the required initial value for the checksum. - An Adler-32 checksum is almost as reliable as a CRC32 but can be computed - much faster. Usage example: - - uLong adler = adler32(0L, Z_NULL, 0); - - while (read_buffer(buffer, length) != EOF) { - adler = adler32(adler, buffer, length); - } - if (adler != original_adler) error(); -*/ - -ZEXTERN uLong ZEXPORT adler32_combine OF((uLong adler1, uLong adler2, - z_off_t len2)); -/* - Combine two Adler-32 checksums into one. For two sequences of bytes, seq1 - and seq2 with lengths len1 and len2, Adler-32 checksums were calculated for - each, adler1 and adler2. adler32_combine() returns the Adler-32 checksum of - seq1 and seq2 concatenated, requiring only adler1, adler2, and len2. -*/ - -ZEXTERN uLong ZEXPORT crc32 OF((uLong crc, const Bytef *buf, uInt len)); -/* - Update a running CRC-32 with the bytes buf[0..len-1] and return the - updated CRC-32. If buf is NULL, this function returns the required initial - value for the for the crc. Pre- and post-conditioning (one's complement) is - performed within this function so it shouldn't be done by the application. - Usage example: - - uLong crc = crc32(0L, Z_NULL, 0); - - while (read_buffer(buffer, length) != EOF) { - crc = crc32(crc, buffer, length); - } - if (crc != original_crc) error(); -*/ - -ZEXTERN uLong ZEXPORT crc32_combine OF((uLong crc1, uLong crc2, z_off_t len2)); - -/* - Combine two CRC-32 check values into one. For two sequences of bytes, - seq1 and seq2 with lengths len1 and len2, CRC-32 check values were - calculated for each, crc1 and crc2. crc32_combine() returns the CRC-32 - check value of seq1 and seq2 concatenated, requiring only crc1, crc2, and - len2. -*/ - - - /* various hacks, don't look :) */ - -/* deflateInit and inflateInit are macros to allow checking the zlib version - * and the compiler's view of z_stream: - */ -ZEXTERN int ZEXPORT deflateInit_ OF((z_streamp strm, int level, - const char *version, int stream_size)); -ZEXTERN int ZEXPORT inflateInit_ OF((z_streamp strm, - const char *version, int stream_size)); -ZEXTERN int ZEXPORT deflateInit2_ OF((z_streamp strm, int level, int method, - int windowBits, int memLevel, - int strategy, const char *version, - int stream_size)); -ZEXTERN int ZEXPORT inflateInit2_ OF((z_streamp strm, int windowBits, - const char *version, int stream_size)); -ZEXTERN int ZEXPORT inflateBackInit_ OF((z_streamp strm, int windowBits, - unsigned char FAR *window, - const char *version, - int stream_size)); - -#define deflateInit(strm, level) \ - deflateInit_((strm), (level), ZLIB_VERSION, sizeof(z_stream)) -#define inflateInit(strm) \ - inflateInit_((strm), ZLIB_VERSION, sizeof(z_stream)) -#define deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ - deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ - (strategy), ZLIB_VERSION, sizeof(z_stream)) -#define inflateInit2(strm, windowBits) \ - inflateInit2_((strm), (windowBits), ZLIB_VERSION, sizeof(z_stream)) -#define inflateBackInit(strm, windowBits, window) \ - inflateBackInit_((strm), (windowBits), (window), \ - ZLIB_VERSION, sizeof(z_stream)) - - -#if !defined(ZUTIL_H) && !defined(NO_DUMMY_DECL) - struct internal_state {int dummy;}; /* hack for buggy compilers */ -#endif - -ZEXTERN const char * ZEXPORT zError OF((int)); -ZEXTERN int ZEXPORT inflateSyncPoint OF((z_streamp z)); -ZEXTERN const uLongf * ZEXPORT get_crc_table OF((void)); - -#ifdef __cplusplus -} -#endif - -#endif /* ZLIB_H */