Add more granular upload-to-blob functions, refactor u2b code

iothub_client/inc/internal/iothub_client_ll_uploadtoblob.h

@@ -40,15 +40,24 @@ extern "C"
     #define BLOCK_SIZE (100*1024*1024)
 
     typedef struct IOTHUB_CLIENT_LL_UPLOADTOBLOB_HANDLE_DATA* IOTHUB_CLIENT_LL_UPLOADTOBLOB_HANDLE;
+
+    /*
+     * @remark `struct IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_STRUCT` contains information specifically
+     *         related to an individual upload request currently active in Azure IoT Hub, mainly
+     *         the correlation-id and Azure Blob SAS URI provided by the Azure IoT Hub when a new
+     *         upload is started. The `struct IOTHUB_CLIENT_LL_UPLOADTOBLOB_HANDLE_DATA` on the other hand 
+     *         holds common information (independent from individual upload requests) that is used for
+     *         upload-to-blob Rest API calls to Azure IoT Hub.
+     */    
     typedef struct IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_STRUCT* IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE;
 
     MOCKABLE_FUNCTION(, IOTHUB_CLIENT_LL_UPLOADTOBLOB_HANDLE, IoTHubClient_LL_UploadToBlob_Create, const IOTHUB_CLIENT_CONFIG*, config, IOTHUB_AUTHORIZATION_HANDLE, auth_handle);
 
     /*
-     * @remark This is a function left in this module for legacy compatibility with the exposed public API for 
+     * @remark This is a legacy function that provides compatibility with the exposed public API for 
      *         upload to blob in iothub_(device|module)_client(_ll) that allowed passing a callback for obtaining the 
-     *         blob blocks data. Since there was quite a lot of (specific) logic put into this function that it
-     *         better reside in this API module.
+     *         blob blocks data. Since there was quite a lot of (specific) logic put into this function, it
+     *         better remain in this API module.
      */
     MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_LL_UploadToBlob_UploadMultipleBlocks, IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE, uploadContextHandle, IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX, getDataCallbackEx, void*, context);
 

iothub_client/inc/iothub_client_core_ll.h

@@ -1,4 +1,3 @@
-
 // Copyright (c) Microsoft. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 

iothub_client/inc/iothub_device_client.h

@@ -355,7 +355,10 @@ extern "C"
     *           This function is expected to be used along with:
     *           `IoTHubDeviceClient_CreateUploadContext`
     *           `IoTHubDeviceClient_AzureStoragePutBlock`
+    *           `IoTHubDeviceClient_AzureStoragePutBlockList`
     *           `IoTHubDeviceClient_DestroyUploadContext`
+    *           `IoTHubDeviceClient_InitializeUpload`
+    *           `IoTHubDeviceClient_NotifyUploadCompletion`
     *           For the standard less-granular uploads to blob please use either
     *           `IoTHubDeviceClient_UploadToBlobAsync` or `IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync`.
     *
@@ -378,7 +381,10 @@ extern "C"
     *           This function is expected to be used along with:
     *           `IoTHubDeviceClient_CreateUploadContext`
     *           `IoTHubDeviceClient_AzureStoragePutBlock`
+    *           `IoTHubDeviceClient_AzureStoragePutBlockList`
     *           `IoTHubDeviceClient_DestroyUploadContext`
+    *           `IoTHubDeviceClient_InitializeUpload`
+    *           `IoTHubDeviceClient_NotifyUploadCompletion`
     *           For the standard less-granular uploads to blob please use either
     *           `IoTHubDeviceClient_UploadToBlobAsync` or `IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync`.
     *
@@ -392,14 +398,19 @@ extern "C"
     MOCKABLE_FUNCTION(, IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE, IoTHubDeviceClient_CreateUploadContext, IOTHUB_DEVICE_CLIENT_HANDLE, iotHubClientHandle, const char*, azureBlobSasUri);
 
     /**
-    * @brief    This API upload a single blob block to Azure Storage (performs a PUT BLOCK operation).
+    * @brief    This API uploads a single blob block to Azure Storage (performs a PUT BLOCK operation).
     * @remark   It is part of a set of functions for more granular control over Azure IoT-based blob uploads.
     *           This function is expected to be used along with:
     *           `IoTHubDeviceClient_CreateUploadContext`
     *           `IoTHubDeviceClient_AzureStoragePutBlock`
+    *           `IoTHubDeviceClient_AzureStoragePutBlockList`
     *           `IoTHubDeviceClient_DestroyUploadContext`
+    *           `IoTHubDeviceClient_InitializeUpload`
+    *           `IoTHubDeviceClient_NotifyUploadCompletion`
     *           For the standard less-granular uploads to blob please use either
     *           `IoTHubDeviceClient_UploadToBlobAsync` or `IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync`.
+    *           For more information about Azure Storage PUT BLOCK, its parameters and behavior, please refer to
+    *           https://learn.microsoft.com/en-us/rest/api/storageservices/put-block
     *
     * @param    uploadContextHandle    The handle created with `IoTHubDeviceClient_CreateUploadContext`.
     * @param    blockNumber            Number of the block being uploaded.
@@ -418,12 +429,17 @@ extern "C"
     *           This function is expected to be used along with:
     *           `IoTHubDeviceClient_CreateUploadContext`
     *           `IoTHubDeviceClient_AzureStoragePutBlock`
+    *           `IoTHubDeviceClient_AzureStoragePutBlockList`
     *           `IoTHubDeviceClient_DestroyUploadContext`
+    *           `IoTHubDeviceClient_InitializeUpload`
+    *           `IoTHubDeviceClient_NotifyUploadCompletion`
     *           For the standard less-granular uploads to blob please use either
     *           `IoTHubDeviceClient_UploadToBlobAsync` or `IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync`.
     *           If this function fails (due to any HTTP error to Azure Storage) it can
     *           be run again for a discretionary number of times in an attempt to succeed after, for example,
-    *           an internet connectivity disruption is over.  
+    *           an internet connectivity disruption is over.
+    *           For more information about Azure Storage PUT BLOCK LIST, please refer to
+    *           https://learn.microsoft.com/en-us/rest/api/storageservices/put-block-list
     *
     * @param    uploadContextHandle    The handle created with `IoTHubDeviceClient_CreateUploadContext`.
     *
@@ -439,6 +455,9 @@ extern "C"
     *           This function is expected to be used along with:
     *           `IoTHubDeviceClient_CreateUploadContext`
     *           `IoTHubDeviceClient_AzureStoragePutBlock`
+    *           `IoTHubDeviceClient_AzureStoragePutBlockList`
+    *           `IoTHubDeviceClient_DestroyUploadContext`
+    *           `IoTHubDeviceClient_InitializeUpload`
     *           `IoTHubDeviceClient_NotifyUploadCompletion`
     *           For the standard less-granular uploads to blob please use either
     *           `IoTHubDeviceClient_UploadToBlobAsync` or `IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync`.
@@ -457,7 +476,10 @@ extern "C"
     *           This function is expected to be used along with:
     *           `IoTHubDeviceClient_CreateUploadContext`
     *           `IoTHubDeviceClient_AzureStoragePutBlock`
+    *           `IoTHubDeviceClient_AzureStoragePutBlockList`
     *           `IoTHubDeviceClient_DestroyUploadContext`
+    *           `IoTHubDeviceClient_InitializeUpload`
+    *           `IoTHubDeviceClient_NotifyUploadCompletion`
     *           For the standard less-granular uploads to blob please use either
     *           `IoTHubDeviceClient_UploadToBlobAsync` or `IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync`.
     *           If this function fails (due to any HTTP error to either Azure Storage or Azure IoT Hub) it can

iothub_client/inc/iothub_device_client_ll.h

@@ -395,6 +395,8 @@ typedef struct IOTHUB_CLIENT_CORE_LL_HANDLE_DATA_TAG* IOTHUB_DEVICE_CLIENT_LL_HA
      * @param    azureBlobSasUri         Variable where to store the Azure Storage SAS URI for the new upload.
      *
      * @warning  This is a synchronous/blocking function.
+     *           This function only attempts to send HTTP requests once, it does not retry in case of failure.
+     *           Any retries must be explicitly implemented by the calling application.
      *           `uploadCorrelationId` and `azureBlobSasUri` must be freed by the calling application
      *           after the blob upload process is done (e.g., after calling `IoTHubDeviceClient_LL_NotifyUploadCompletion`).
      *
@@ -422,21 +424,25 @@ typedef struct IOTHUB_CLIENT_CORE_LL_HANDLE_DATA_TAG* IOTHUB_DEVICE_CLIENT_LL_HA
      MOCKABLE_FUNCTION(, IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE, IoTHubDeviceClient_LL_CreateUploadContext, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, const char*, azureBlobSasUri);
 
      /**
-     * @brief    This API upload a single blob block to Azure Storage (performs a PUT BLOCK operation).
+     * @brief    This API uploads a single blob block to Azure Storage (performs a PUT BLOCK operation).
      * @remark   It is part of a set of functions for more granular control over Azure IoT-based blob uploads.
      *           This function is expected to be used along with:
      *           `IoTHubDeviceClient_LL_CreateUploadContext`
      *           `IoTHubDeviceClient_LL_NotifyUploadCompletion`
      *           `IoTHubDeviceClient_LL_DestroyUploadContext`
      *           For the standard less-granular uploads to blob please use either
      *           `IoTHubDeviceClient_LL_UploadToBlob` or `IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob`.
+     *           For more information about Azure Storage PUT BLOCK, its parameters and behavior, please refer to
+     *           https://learn.microsoft.com/en-us/rest/api/storageservices/put-block
      *
      * @param    uploadContextHandle    The handle created with `IoTHubDeviceClient_LL_CreateUploadContext`.
      * @param    blockNumber            Number of the block being uploaded.
      * @param    dataPtr                Pointer to the block data to be uploaded to Azure Storage blob.
      * @param    dataSize               Size of the block data pointed by `dataPtr`.
      *
      * @warning  This is a synchronous/blocking function.
+     *           This function only attempts to send HTTP requests once, it does not retry in case of failure.
+     *           Any retries must be explicitly implemented by the calling application.
      *
      * @return   IOTHUB_CLIENT_OK upon success or an error code upon failure.
      */
@@ -451,10 +457,14 @@ typedef struct IOTHUB_CLIENT_CORE_LL_HANDLE_DATA_TAG* IOTHUB_DEVICE_CLIENT_LL_HA
      *           `IoTHubDeviceClient_LL_DestroyUploadContext`
      *           For the standard less-granular uploads to blob please use either
      *           `IoTHubDeviceClient_LL_UploadToBlob` or `IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob`.
+     *           For more information about Azure Storage PUT BLOCK LIST, please refer to
+     *           https://learn.microsoft.com/en-us/rest/api/storageservices/put-block-list
      *
      * @param    uploadContextHandle    The handle created with `IoTHubDeviceClient_LL_CreateUploadContext`.
      *
      * @warning  This is a synchronous/blocking function.
+     *           This function only attempts to send HTTP requests once, it does not retry in case of failure.
+     *           Any retries must be explicitly implemented by the calling application.
      *
      * @return   IOTHUB_CLIENT_OK upon success or an error code upon failure.
      */
@@ -498,7 +508,9 @@ typedef struct IOTHUB_CLIENT_CORE_LL_HANDLE_DATA_TAG* IOTHUB_DEVICE_CLIENT_LL_HA
      * @param    responseMessage        An user-defined status message to go along with `responseCode` on the notification to Azure IoT Hub.
      *
      * @warning  This is a synchronous/blocking function.
-     *
+     *           This function only attempts to send HTTP requests once, it does not retry in case of failure.
+     *           Any retries must be explicitly implemented by the calling application.
+     * 
      * @return   IOTHUB_CLIENT_OK upon success or an error code upon failure.
      */
      MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_NotifyUploadCompletion, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, const char*, uploadCorrelationId, bool, isSuccess, int, responseCode, const char*, responseMessage);

iothub_client/samples/iothub_client_sample_upload_to_blob/iothub_client_sample_upload_to_blob.c

@@ -35,6 +35,7 @@ static const char* connectionString = "[device connection string]";
 static const char* proxyHost = NULL;
 static int proxyPort = 0;
 
+static const char* azureStorageBlobPath = "subdir/hello_world.txt";
 #define HELLO_WORLD "Hello World from IoTHubDeviceClient_LL_UploadToBlob"
 
 int main(void)
@@ -73,7 +74,7 @@ int main(void)
         }
         else
         {
-            if (IoTHubDeviceClient_LL_UploadToBlob(device_ll_handle, "subdir/hello_world.txt", (const unsigned char*)HELLO_WORLD, sizeof(HELLO_WORLD) - 1) != IOTHUB_CLIENT_OK)
+            if (IoTHubDeviceClient_LL_UploadToBlob(device_ll_handle, azureStorageBlobPath, (const unsigned char*)HELLO_WORLD, sizeof(HELLO_WORLD) - 1) != IOTHUB_CLIENT_OK)
             {
                 (void)printf("hello world failed to upload\n");
             }

iothub_client/samples/iothub_client_sample_upload_to_blob_custom/iothub_client_sample_upload_to_blob_custom.c

@@ -35,6 +35,7 @@ static const char* connectionString = "[device connection string]";
 static const char* proxyHost = NULL;
 static int proxyPort = 0;
 
+static const char* azureStorageBlobPath = "subdir/hello_world_custom_mb.txt";
 static const char* data_to_upload_format = "Hello World from iothub_client_sample_upload_to_blob_custom: %d\n";
 static char data_to_upload[128];
 
@@ -76,10 +77,9 @@ int main(void)
         {
             char* uploadCorrelationId;
             char* azureBlobSasUri;
-            const char* bla = "subdir/hello_world_custom_mb.txt";
 
             if (IoTHubDeviceClient_LL_InitializeUpload(
-                    device_ll_handle, bla, &uploadCorrelationId, &azureBlobSasUri) != IOTHUB_CLIENT_OK)
+                    device_ll_handle, azureStorageBlobPath, &uploadCorrelationId, &azureBlobSasUri) != IOTHUB_CLIENT_OK)
             {
                 printf("failed initializing upload in IoT Hub\n");
             }

iothub_client/samples/iothub_client_sample_upload_to_blob_mb/iothub_client_sample_upload_to_blob_mb.c

@@ -33,6 +33,7 @@ static const char* connectionString = "[device connection string]";
 /*Optional string with http proxy host and integer for http proxy port (Linux only)         */
 static const char* proxyHost = NULL;
 static int proxyPort = 0;
+static const char* azureStorageBlobPath = "subdir/hello_world_mb.txt";
 static const char* data_to_upload_format = "Hello World from IoTHubDeviceClient_LL_UploadToBlob block: %d\n";
 static char data_to_upload[128];
 static int block_count = 0;
@@ -124,7 +125,7 @@ int main(void)
         }
         else
         {
-            if (IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob(device_ll_handle, "subdir/hello_world_mb.txt", getDataCallback, NULL) != IOTHUB_CLIENT_OK)
+            if (IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob(device_ll_handle, azureStorageBlobPath, getDataCallback, NULL) != IOTHUB_CLIENT_OK)
             {
                 (void)printf("hello world failed to upload\n");
             }

iothub_client/src/blob.c

@@ -19,6 +19,14 @@ static const char blockListUriMarker[] = "&comp=blocklist";
 static const char blockListLatestTagXmlBegin[] = "<Latest>";
 static const char blockListLatestTagXmlEnd[] = "</Latest>";
 
+// Size of the string containing an Azure Blob Block ID.
+// For more details please see
+// https://learn.microsoft.com/en-us/rest/api/storageservices/put-block?tabs=azure-ad#uri-parameters
+#define AZURE_BLOB_BLOCK_ID_SIZE 7
+
+// Length of the string representation of an Azure Blob Block ID (enough to represent "049999").
+#define AZURE_BLOB_BLOCK_ID_LENGTH 6
+
 static STRING_HANDLE createBlockIdListXml(SINGLYLINKEDLIST_HANDLE blockIDList)
 {
     STRING_HANDLE blockIdListXml;
@@ -147,9 +155,9 @@ BLOB_RESULT Blob_PutBlock(
         result = BLOB_ERROR;
     }
     else
-    {
-        char blockIdString[7]; /*this will contain 000000... 049999*/
-        if (sprintf(blockIdString, "%6u", (unsigned int)blockID) != 6) /*produces 000000... 049999*/
+    {   
+        char blockIdString[AZURE_BLOB_BLOCK_ID_SIZE]; /*this will contain 000000... 049999*/
+        if (sprintf(blockIdString, "%6u", (unsigned int)blockID) != AZURE_BLOB_BLOCK_ID_LENGTH) /*produces 000000... 049999*/
         {
             LogError("failed to sprintf");
             result = BLOB_ERROR;

iothub_client/src/iothub_client_core.c

@@ -2509,9 +2509,7 @@ IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE IoTHubClientCore_CreateUploadContex
 {
     IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE result;
 
-    if (
-        (iotHubClientHandle == NULL)
-        )
+    if (iotHubClientHandle == NULL)
     {
         LogError("invalid parameters iotHubClientHandle = %p", iotHubClientHandle);
         result = NULL;