Update the storage readme with concepts (Azure#1005)

* Update the storage readme with concepts

* Update app -> application
Move the context into the options to be consistent with C++ and the context being optional for callers of convenience layer APIs

* Information on how to replace the http stack

sdk/docs/storage/README.md

@@ -2,52 +2,70 @@
 
 Azure Storage Blobs library (`az_storage_blobs`) provides abstractions, and helpers for communicating with Azure Storage Blobs in the C programming language. This library follows the Azure SDK Design Guidelines for Embedded C.
 
-Use the Azure SDK Storage Blobs Library for Embedded C to work with Azure Storage Blobs.
+The Azure SDK Storage Blobs Library for Embedded C can be used for the following actions:
 
 * Upload blobs
-* Create and modify blob metadata
 
 ## Getting Started
 
-### Install the Package
+The Azure Storage Blobs Client library facilitates connectivity to the Azure Storage Blobs service. Since this service uses HTTP, you must plug in an HTTP adapter capable of sending the HTTP request to your device's HTTP stack. For information on how to do this, please see [this page][docs_platform_readme].
 
-TODO link to the vcpkg
+### Docs
 
-### Authenticate the Client
+For API documentation, please see the doxygen generated docs [here][azure_sdk_for_c_doxygen_docs]. You can find the Storage Blobs specific docs by navigating to the **Files -> File List** section near the top and choosing any of the header files prefixed with `az_storage_blobs`.
 
-TODO
+### Build
 
-### Get Credentials
+The Azure Storage Blobs library is compiled following the same steps listed on the root [README][azure_sdk_for_c_readme] documentation, under ["Getting Started Using the SDK"][azure_sdk_for_c_readme_getting_started].
 
-TODO
+The library targets made available via CMake are the following:
 
-### Create Client
+- `az::storage::blobs` - For Azure Storage Blobs features ([API documentation here][azure_sdk_for_c_doxygen_docs])
 
-TODO
+### Samples
+
+This [page][samples_storage_blobs_readme] explains samples for the Azure Embedded C SDK Storage Blobs Client.
+
+
+### Prerequisites
+
+For compiling the Azure SDK for Embedded C for the most common platforms (Windows and Linux), no further prerequisites are necessary.
+Please follow the instructions in the [Getting Started](#Getting-Started) section above.
+For compiling for specific target devices, please refer to their specific toolchain documentation.
 
 ## Key Concepts
 
-TODO
+### Authentication
+
+The embedded C SDK currently supports SAS based authentication.  See [this page][storage_access_control_sas] for information on creating SAS tokens.
+The client credential should be set to `AZ_CREDENTIAL_ANONYMOUS` when using SAS tokens.
 
-## Examples
+### Creating the Storage Client
 
-TODO
+To use the storage client, the first action is to initialize the client with `az_storage_blobs_blob_client_init`.
+```C
+  az_storage_blobs_blob_client client;
+  az_storage_blobs_blob_client_options options = az_storage_blobs_blob_client_options_default();
 
-## Troubleshooting
+  az_storage_blobs_blob_client_init(
+          &client, az_span_from_str(getenv(URI_ENV)), AZ_CREDENTIAL_ANONYMOUS, &options);
+```
 
-### General
+### Uploading a blob
 
-TODO
+Once the client is created it can be used to upload blobs.
+```C
+  az_result const blob_upload_result = az_storage_blobs_blob_upload(
+      &client, &az_context_application, content_to_upload, NULL, &http_response)
+```
 
 ### Retry Policy
 
 While working with Storage, you might encounter transient failures caused by [rate limits][storage_rate_limits] enforced by the service, or other transient problems like network outages. For information about handling these types of failures, see [Retry pattern][azure_pattern_retry] in the Cloud Design Patterns guide, and the related [Circuit Breaker pattern][azure_pattern_circuit_breaker].
 
-## Next Steps
-
-### More Sample Code
+## Need Help
 
-TODO
+- File an issue via [Github Issues](https://github.com/Azure/azure-sdk-for-c/issues/new/choose).
 
 ### Additional Documentation
 
@@ -62,20 +80,20 @@ If you'd like to contribute to this library, please read the [contributing guide
 Azure SDK for Embedded C is licensed under the [MIT][azure_sdk_for_c_license] license.
 
 <!-- LINKS -->
+[azure_pattern_circuit_breaker]: https://docs.microsoft.com/azure/architecture/patterns/circuit-breaker
+[azure_pattern_retry]: https://docs.microsoft.com/azure/architecture/patterns/retry
 [azure_sdk_for_c_contributing]: ../../../CONTRIBUTING.md
-[azure_sdk_for_c_license]: https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE
 [azure_sdk_for_c_contributing_developer_guide]: ../../../CONTRIBUTING.md#developer-guide
 [azure_sdk_for_c_contributing_pull_requests]: ../../../CONTRIBUTING.md#pull-requests
-[azure_cli]: https://docs.microsoft.com/cli/azure
-[azure_pattern_circuit_breaker]: https://docs.microsoft.com/azure/architecture/patterns/circuit-breaker
-[azure_pattern_retry]: https://docs.microsoft.com/azure/architecture/patterns/retry
-[azure_portal]: https://portal.azure.com
-[azure_sub]: https://azure.microsoft.com/free/
-[c_compiler]: https://visualstudio.microsoft.com/vs/features/cplusplus/
-[cloud_shell]: https://docs.microsoft.com/azure/cloud-shell/overview
-[cloud_shell_bash]: https://shell.azure.com/bash
+[azure_sdk_for_c_doxygen_docs]: https://azure.github.io/azure-sdk-for-c
+[azure_sdk_for_c_license]: ../../../LICENSE
+[azure_sdk_for_c_readme]: ../../../README.md
+[azure_sdk_for_c_readme_getting_started]:../../../README.md#getting-started-using-the-sdk
+[samples_storage_blobs_readme]: ../../samples/storage/blobs/README.md
+[docs_platform_readme]: ../platform/README.md
+[storage_access_control_sas]: https://docs.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature
 [storage_account_create]: https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal
 [storage_blobs]: https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-overview
 [storage_docs]: https://docs.microsoft.com/azure/storage/
-[storage_overview]: https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction
 [storage_rate_limits]: https://docs.microsoft.com/en-us/azure/storage/blobs/scalability-targets
+[storage_overview]: https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction

sdk/inc/azure/core/az_context.h

@@ -89,7 +89,7 @@ az_context_create_with_value(az_context const* parent, void const* key, void con
  * @brief Cancels the specified #az_context node; this cancels all the child nodes as well.
  *
  * @param[in] context A pointer to the #az_context node to be canceled; passing `NULL` cancels the
- * root #az_context_app.
+ * root #az_context.
  */
 AZ_INLINE void az_context_cancel(az_context* context)
 {

sdk/inc/azure/storage/az_storage_blobs.h

@@ -90,6 +90,7 @@ AZ_NODISCARD az_result az_storage_blobs_blob_client_init(
  */
 typedef struct
 {
+  az_context* context;
   struct
   {
     az_span unused;
@@ -118,14 +119,14 @@ AZ_NODISCARD az_storage_blobs_blob_client_options az_storage_blobs_blob_client_o
 AZ_NODISCARD AZ_INLINE az_storage_blobs_blob_upload_options
 az_storage_blobs_blob_upload_options_default()
 {
-  return (az_storage_blobs_blob_upload_options){ ._internal = { .unused = AZ_SPAN_NULL } };
+  return (az_storage_blobs_blob_upload_options){ .context = &az_context_application,
+                                                ._internal = { .unused = AZ_SPAN_NULL } };
 }
 
 /**
  * @brief Uploads the contents to blob storage.
  *
  * @param client A storage blobs client structure.
- * @param context Supports cancelling long running operations.
  * @param content The blob content to upload.
  * @param options __[nullable]__ A reference to an #az_storage_blobs_blob_upload_options
  * structure which defines custom behavior for uploading the blob. If `NULL` is passed, the client
@@ -137,7 +138,6 @@ az_storage_blobs_blob_upload_options_default()
  */
 AZ_NODISCARD az_result az_storage_blobs_blob_upload(
     az_storage_blobs_blob_client* client,
-    az_context* context,
     az_span content, /* Buffer of content*/
     az_storage_blobs_blob_upload_options* options,
     az_http_response* response);

sdk/samples/storage/blobs/src/blobs_client_example.c

@@ -92,7 +92,7 @@ int main()
   // 3) upload content
   printf("Uploading blob...\n");
   az_result const blob_upload_result = az_storage_blobs_blob_upload(
-      &client, &az_context_application, content_to_upload, NULL, &http_response);
+      &client, content_to_upload, NULL, &http_response);
 
   // This validation is only for the first time SDK client is used. API will return not implemented
   // if samples were built with no_http lib.

sdk/src/azure/storage/az_storage_blobs_blob_client.c

@@ -130,7 +130,6 @@ AZ_NODISCARD az_result az_storage_blobs_blob_client_init(
 
 AZ_NODISCARD az_result az_storage_blobs_blob_upload(
     az_storage_blobs_blob_client* client,
-    az_context* context,
     az_span content, /* Buffer of content*/
     az_storage_blobs_blob_upload_options* options,
     az_http_response* response)
@@ -163,7 +162,7 @@ AZ_NODISCARD az_result az_storage_blobs_blob_upload(
   az_http_request request;
   AZ_RETURN_IF_FAILED(az_http_request_init(
       &request,
-      context,
+      opt.context,
       az_http_method_put(),
       request_url_span,
       uri_size,