diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e8b37b70d..5f6371dd5b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -161,5 +161,5 @@ make ${project_name}_cov_xml //i.e. az_core_cov_xml or az_iot_cov_xml ``` -[vcpkg]: ./README.md#development-environment +[vcpkg]: https://github.com/Azure/azure-sdk-for-c/blob/master/README.md#development-environment [azure_sdk_for_c_cmake_options]: https://github.com/Azure/azure-sdk-for-c#cmake-options diff --git a/README.md b/README.md index 780a967de4..37c11e463d 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ With this in mind, there are many tenets or principles that we follow in order t - Unlike our other language SDKs, many things (such as composing an HTTP pipeline of policies) are done in source code as opposed to runtime. This reduces code size, improves execution speed and locks-in behavior, reducing the chance of bugs at runtime. -- We support microcontrollers with no operating system, microcontrollers with a real-time operating system (like [Azure RTOS](https://azure.microsoft.com/en-us/services/rtos/)), Linux, and Windows. Customers can implement custom platform layers to use our SDK on custom devices. We provide some platform layers, and encourage the community to submit platform layers to increase the out-of-the-box supported platforms. +- We support microcontrollers with no operating system, microcontrollers with a real-time operating system (like [Azure RTOS](https://azure.microsoft.com/services/rtos/)), Linux, and Windows. Customers can implement custom platform layers to use our SDK on custom devices. We provide some platform layers, and encourage the community to submit platform layers to increase the out-of-the-box supported platforms. ## Table of Contents @@ -63,8 +63,8 @@ To get help with the SDK: The Azure SDK for Embedded C repo has been structured around the service libraries it provides: -1. [IoT](sdk/docs/iot) - Library to connect Embedded Devices to Azure IoT services -2. [Storage](sdk/docs/storage) - Library to send blob files to Azure IoT services +1. [IoT](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot) - Library to connect Embedded Devices to Azure IoT services +2. [Storage](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/storage) - Library to send blob files to Azure IoT services ### Structure @@ -113,7 +113,7 @@ The SDK can be conveniently consumed either via CMake or other non-CMake methods git checkout - For information about using a specific client library, see the README file located in the client library's folder which is a subdirectory under the [`/sdk/docs`](sdk/docs) folder. + For information about using a specific client library, see the README file located in the client library's folder which is a subdirectory under the [`/sdk/docs`](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs) folder. 3. Ensure the SDK builds correctly. @@ -242,7 +242,7 @@ The following compilation, preprocessor options will add or remove functionality See [cmake options](#cmake-options) to learn about how to build samples with HTTP implementation in order to be runnable. -After building samples with HTTP stack, set the environment variables for credentials. The samples read these environment values to authenticate to Azure services. See [client secret here](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-oauth2-on-behalf-of-flow#service-to-service-access-token-request) for additional details on Azure authentication. +After building samples with HTTP stack, set the environment variables for credentials. The samples read these environment values to authenticate to Azure services. See [client secret here](https://docs.microsoft.com/azure/active-directory/azuread-dev/v1-oauth2-on-behalf-of-flow#service-to-service-access-token-request) for additional details on Azure authentication. ```bash # On linux, set env var like this. For Windows, do it from advanced settings/ env variables @@ -280,7 +280,7 @@ files and start again. vcpkg is the easiest way to have dependencies installed. It downloads packages sources, headers and build libraries for whatever TRIPLET is set up (platform/arq). VCPKG maintains any installed package inside its own folder, allowing to have multiple vcpkg folder with different dependencies installed on each. This is also great because you don't have to install dependencies globally on your system. -Follow next steps to install VCPKG and have it linked to cmake. The vcpkg repository is checked out at the commit in [vcpkg-commit.txt](eng/vcpkg-commit.txt). Azure SDK code in this version is known to work at that vcpkg ref. +Follow next steps to install VCPKG and have it linked to cmake. The vcpkg repository is checked out at the commit in [vcpkg-commit.txt](https://github.com/Azure/azure-sdk-for-c/blob/master/eng/vcpkg-commit.txt). Azure SDK code in this version is known to work at that vcpkg ref. ```bash # Clone vcpkg: @@ -332,7 +332,7 @@ Right after opening project, Visual Studio will read cmake files and generate ca VCPKG can be used to download packages sources, headers and build libraries for whatever TRIPLET is set up (platform/architecture). VCPKG maintains any installed package inside its own folder, allowing to have multiple vcpkg folder with different dependencies installed on each. This is also great because you don't have to install dependencies globally on your system. -Follow next steps to install VCPKG and have it linked to cmake. Follow next steps to install VCPKG and have it linked to cmake. The vcpkg repository is checked out at the commit in [vcpkg-commit.txt](eng/vcpkg-commit.txt). Azure SDK code in this version is known to work at that vcpkg ref. +Follow next steps to install VCPKG and have it linked to cmake. Follow next steps to install VCPKG and have it linked to cmake. The vcpkg repository is checked out at the commit in [vcpkg-commit.txt](https://github.com/Azure/azure-sdk-for-c/blob/master/eng/vcpkg-commit.txt). Azure SDK code in this version is known to work at that vcpkg ref. ```bash # Clone vcpkg: @@ -389,7 +389,7 @@ First, ensure that you have the latest `gcc` installed: brew install gcc brew cleanup -Follow next steps to install VCPKG and have it linked to cmake. Follow next steps to install VCPKG and have it linked to cmake. The vcpkg repository is checked out at the commit in [vcpkg-commit.txt](eng/vcpkg-commit.txt). Azure SDK code in this version is known to work at that vcpkg ref. +Follow next steps to install VCPKG and have it linked to cmake. Follow next steps to install VCPKG and have it linked to cmake. The vcpkg repository is checked out at the commit in [vcpkg-commit.txt](https://github.com/Azure/azure-sdk-for-c/blob/master/eng/vcpkg-commit.txt). Azure SDK code in this version is known to work at that vcpkg ref. ```bash # Clone vcpkg: @@ -454,7 +454,7 @@ See the complete cmake file and how to link your own library [here](https://gith ## SDK Architecture -At the heart of our SDK is, what we refer to as, [Azure Core](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/core). This code defines several data types and functions for use by the client libraries that build on top of us such as an [Azure Storage Blob](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/storage) client library and [Azure IoT client libraries](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot). Here are some of the features that customers use directly: +At the heart of our SDK is, what we refer to as, [Azure Core](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/core). This code defines several data types and functions for use by the client libraries that build on top of us such as an [Azure Storage Blob](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/storage) client library and [Azure IoT client libraries](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot). Here are some of the features that customers use directly: - **Spans**: A span represents a byte buffer and is used for string manipulations, HTTP requests/responses, reading/writing JSON payloads. It allows us to return a substring within a larger string without any memory allocations. See the [Working With Spans](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/core#working-with-spans) section of the `Azure Core` README for more information. @@ -472,7 +472,7 @@ In addition to the above features, `Azure Core` provides features available to c ## Contributing -For details on contributing to this repository, see the [contributing guide](CONTRIBUTING.md). +For details on contributing to this repository, see the [contributing guide](https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md). This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [https://cla.microsoft.com](https://cla.microsoft.com). @@ -487,8 +487,8 @@ For more information see the [Code of Conduct FAQ](https://opensource.microsoft. Many people all over the world have helped make this project better. You'll want to check out: - [What are some good first issues for new contributors to the repo?](https://github.com/azure/azure-sdk-for-c/issues?q=is%3Aopen+is%3Aissue+label%3A%22up+for+grabs%22) -- [How to build and test your change](./CONTRIBUTING.md#developer-guide) -- [How you can make a change happen!](./CONTRIBUTING.md#pull-requests) +- [How to build and test your change](https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md#developer-guide) +- [How you can make a change happen!](https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md#pull-requests) ### Community diff --git a/SECURITY.md b/SECURITY.md index 926b8ae405..dec3d3b701 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,7 +4,7 @@ Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). -If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. ## Reporting Security Issues @@ -12,7 +12,7 @@ If you believe you have found a security vulnerability in any Microsoft-owned re Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report). -If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc). +If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/msrc/pgp-key-msrc). You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). @@ -36,6 +36,6 @@ We prefer all communications to be in English. ## Policy -Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd). +Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/msrc/cvd). diff --git a/eng/pipelines/templates/jobs/archetype-sdk-client.yml b/eng/pipelines/templates/jobs/archetype-sdk-client.yml index 9ea94839d2..a836ca07b5 100644 --- a/eng/pipelines/templates/jobs/archetype-sdk-client.yml +++ b/eng/pipelines/templates/jobs/archetype-sdk-client.yml @@ -385,6 +385,7 @@ jobs: - template: /eng/common/pipelines/templates/steps/verify-links.yml parameters: Directory: '' + CheckLinkGuidance: $true # Generate release-info - pwsh: >- @@ -416,14 +417,6 @@ jobs: artifactName: release-info path: $(Build.ArtifactStagingDirectory)/release-info - # Update links - - template: /eng/common/pipelines/templates/steps/replace-relative-links.yml - parameters: - TargetFolder: . - RootFolder: . - BuildSHA: $(Build.SourceVersion) - RepoId: 'Azure/azure-sdk-for-c' - # Generate Documentation - pwsh: | $setupFile="doxygen-1.8.20-setup.exe"; diff --git a/sdk/docs/core/README.md b/sdk/docs/core/README.md index 8576d820ad..e314483e76 100644 --- a/sdk/docs/core/README.md +++ b/sdk/docs/core/README.md @@ -16,7 +16,7 @@ Many SDK functions return an `az_result` as defined in [inc/az_result.h](https:/ ### Working with Spans -An `az_span` is a small data structure (defined in our [az_span.h](../../../sdk/inc/azure/core/az_span.h) file) wrapping a byte buffer. Specifically, an `az_span` instance contains: +An `az_span` is a small data structure (defined in our [az_span.h](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/inc/azure/core/az_span.h) file) wrapping a byte buffer. Specifically, an `az_span` instance contains: - a byte pointer - an integer size @@ -72,7 +72,7 @@ There are many functions to manipulate `az_span` instances. You can slice (subse ### Strings -A string is a span of UTF-8 characters. It's not a zero-terminated string. Defined in [inc/az_span.h](../../../sdk/inc/azure/core/az_span.h). +A string is a span of UTF-8 characters. It's not a zero-terminated string. Defined in [inc/az_span.h](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/inc/azure/core/az_span.h). ```c az_span hello_world = AZ_SPAN_FROM_STR("Hello world!"); @@ -162,10 +162,10 @@ 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. -[azure_sdk_for_c_contributing]: ../../../CONTRIBUTING.md +[azure_sdk_for_c_contributing]: https://github.com/Azure/azure-sdk-for-c/blob/master/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_sdk_for_c_contributing_developer_guide]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md#developer-guide +[azure_sdk_for_c_contributing_pull_requests]: https://github.com/Azure/azure-sdk-for-c/blob/master/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 diff --git a/sdk/docs/iot/README.md b/sdk/docs/iot/README.md index 173d5b358e..e4553634dd 100644 --- a/sdk/docs/iot/README.md +++ b/sdk/docs/iot/README.md @@ -37,7 +37,7 @@ From a functional perspective, this means that the user's application code (not A full list of features can be found in the doxygen docs listed below in [Docs](#docs). -**Note**: this therefore requires a different programming model as compared to the earlier version of the C SDK ([found here](https://github.com/Azure/azure-iot-sdk-c)). To better understand the responsibilities of the user application code and the SDK, please take a look at the [State Machine diagram](mqtt_state_machine.md) that explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities. +**Note**: this therefore requires a different programming model as compared to the earlier version of the C SDK ([found here](https://github.com/Azure/azure-iot-sdk-c)). To better understand the responsibilities of the user application code and the SDK, please take a look at the [State Machine diagram](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md) that explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities. ### Docs @@ -45,7 +45,7 @@ For API documentation, please see the doxygen generated docs [here][azure_sdk_fo ### Build -The Azure IoT library is compiled following the same steps listed on the root [README](../../../README.md) documentation, under ["Getting Started Using the SDK"](../../../README.md#getting-started-using-the-sdk). +The Azure IoT library is compiled following the same steps listed on the root [README](https://github.com/Azure/azure-sdk-for-c/blob/master/README.md) documentation, under ["Getting Started Using the SDK"](https://github.com/Azure/azure-sdk-for-c/blob/master/README.md#getting-started-using-the-sdk). The library targets made available via CMake are the following: @@ -54,15 +54,15 @@ The library targets made available via CMake are the following: ### Samples -[This page](../../../sdk/samples/iot/README.md) explains samples for the Azure Embedded C SDK IoT Hub Client and the Provisioning Clients and how to use them. +[This page](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md) explains samples for the Azure Embedded C SDK IoT Hub Client and the Provisioning Clients and how to use them. For step-by-step guides starting from scratch, you may refer to these documents: -- Linux: [How to Setup and Run Azure SDK for Embedded C IoT Hub Samples on Linux](../../../sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md) +- Linux: [How to Setup and Run Azure SDK for Embedded C IoT Hub Samples on Linux](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md) -- Windows: [How to Setup and Run Azure SDK for Embedded C IoT Hub Samples on Microsoft Windows](../../../sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md). +- Windows: [How to Setup and Run Azure SDK for Embedded C IoT Hub Samples on Microsoft Windows](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md). -- ESP8266: [How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Esp8266 NodeMCU](../../../sdk/samples/iot/docs/how_to_iot_hub_esp8266_nodemcu.md) +- ESP8266: [How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Esp8266 NodeMCU](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_esp8266_nodemcu.md) **Important Note on Linux and Windows Samples**: While Windows and Linux devices are not likely to be considered as constrained ones, these samples were created to make it simpler to test the Azure SDK for Embedded C libraries, debug and step through the code to learn about it, even without a real device. We understand not everyone will have a real device to test and - sometimes - these devices won't have debugging capabilities. @@ -89,7 +89,7 @@ Feature | Azure SDK for Embedded C | Description [DPS - Device Provisioning Service](https://docs.microsoft.com/azure/iot-dps/) | √ | This SDK supports connecting your device to the Device Provisioning Service via, for example, [individual enrollment](https://docs.microsoft.com/azure/iot-dps/concepts-service#enrollment) using an [X.509 leaf certificate](https://docs.microsoft.com/azure/iot-dps/concepts-security#leaf-certificate). Protocol | MQTT | The Azure SDK for Embedded C supports only MQTT. Retry Policies | √* | The Azure SDK for Embedded C provides guidelines for retries, but actual retries should be handled by the application. - [IoT Plug and Play](https://docs.microsoft.com/en-us/azure/iot-pnp/overview-iot-plug-and-play) | √ | IoT Plug and Play Preview enables solution developers to integrate devices with their solutions without writing any embedded code. + [IoT Plug and Play](https://docs.microsoft.com/azure/iot-pnp/overview-iot-plug-and-play) | √ | IoT Plug and Play Preview enables solution developers to integrate devices with their solutions without writing any embedded code. ## Examples @@ -331,7 +331,7 @@ 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. -[azure_sdk_for_c_contributing]: ../../../CONTRIBUTING.md +[azure_sdk_for_c_contributing]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md [azure_sdk_for_c_doxygen_docs]: https://azure.github.io/azure-sdk-for-c [azure_sdk_for_c_doxygen_hub_docs]: https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0-preview.2/az__iot__hub__client_8h.html [azure_sdk_for_c_doxygen_provisioning_docs]: https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0-preview.2/az__iot__provisioning__client_8h.html diff --git a/sdk/docs/iot/hub.md b/sdk/docs/iot/hub.md index 0e7e331035..83a7aef274 100644 --- a/sdk/docs/iot/hub.md +++ b/sdk/docs/iot/hub.md @@ -4,7 +4,7 @@ Official Embedded C client for Azure IoT Hub. ## Getting Started -- **Docs**: If you're new to the Azure SDK for Embedded C take a look at the [State Machine diagram](./mqtt_state_machine.md#iot-hub) that explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities. +- **Docs**: If you're new to the Azure SDK for Embedded C take a look at the [State Machine diagram](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md#iot-hub) that explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities. - **Samples**: [This page](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/) explains samples for the Azure SDK for Embedded C and how to use them. ## Need Help? @@ -22,5 +22,5 @@ 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. -[azure_sdk_for_c_contributing]: ../../../CONTRIBUTING.md +[azure_sdk_for_c_contributing]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md [azure_sdk_for_c_license]: https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE diff --git a/sdk/docs/iot/mqtt_state_machine.md b/sdk/docs/iot/mqtt_state_machine.md index 5bcfe25888..ea531f4117 100644 --- a/sdk/docs/iot/mqtt_state_machine.md +++ b/sdk/docs/iot/mqtt_state_machine.md @@ -19,7 +19,7 @@ The following aspects need to be handled by the application or convenience layer 1. Delay execution for retry purposes. 1. (Optional) Provide real-time clock information and perform HMAC-SHA256 operations for SAS token generation. -For more information about Azure IoT services using MQTT see [this article](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support). +For more information about Azure IoT services using MQTT see [this article](https://docs.microsoft.com/azure/iot-hub/iot-hub-mqtt-support). ## Components @@ -194,7 +194,7 @@ else #### Retry Timing -Network timeouts and the MQTT keep-alive interval should be configured considering tradeoffs between how fast network issues are detected vs traffic overheads. [This document](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support#default-keep-alive-timeout) describes the recommended keep-alive timeouts as well as the minimum idle timeout supported by Azure IoT services. +Network timeouts and the MQTT keep-alive interval should be configured considering tradeoffs between how fast network issues are detected vs traffic overheads. [This document](https://docs.microsoft.com/azure/iot-hub/iot-hub-mqtt-support#default-keep-alive-timeout) describes the recommended keep-alive timeouts as well as the minimum idle timeout supported by Azure IoT services. For connectivity issues at all layers (TCP, TLS, MQTT) as well as cases where there is no `retry-after` sent by the service, we suggest using an exponential back-off with random jitter function. `az_iot_retry_calc_delay` is available in Azure IoT Common: @@ -207,7 +207,7 @@ int32_t delay_msec = az_iot_calculate_retry_delay(operation_msec, attempt, min_r _Note 1_: The network stack may have used more time than the recommended delay before timing out. (e.g. The operation timed out after 2 minutes while the delay between operations is 1 second). In this case there is no need to delay the next operation. -_Note 2_: To determine the parameters of the exponential with back-off retry strategy, we recommend modeling the network characteristics (including failure-modes). Compare the results with defined SLAs for device connectivity (e.g. 1M devices must be connected in under 30 minutes) and with the available [IoT Azure scale](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-quotas-throttling) (especially consider _throttling_, _quotas_ and maximum _requests/connects per second_). +_Note 2_: To determine the parameters of the exponential with back-off retry strategy, we recommend modeling the network characteristics (including failure-modes). Compare the results with defined SLAs for device connectivity (e.g. 1M devices must be connected in under 30 minutes) and with the available [IoT Azure scale](https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-quotas-throttling) (especially consider _throttling_, _quotas_ and maximum _requests/connects per second_). In the absence of modeling, we recommend the following default: diff --git a/sdk/docs/iot/provisioning.md b/sdk/docs/iot/provisioning.md index 40b7b2615b..93578c0a0c 100644 --- a/sdk/docs/iot/provisioning.md +++ b/sdk/docs/iot/provisioning.md @@ -6,7 +6,7 @@ For more details about Provisioning Service check [Azure documentation](https:// ## Getting Started -- Please refer to the state machine diagram which describes the Azure SDK for Embedded C flow for Provisioning Service [here](./mqtt_state_machine.md#device-provisioning-service). +- Please refer to the state machine diagram which describes the Azure SDK for Embedded C flow for Provisioning Service [here](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md#device-provisioning-service). - **Samples**: [This page](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md) explains samples for the Azure SDK for Embedded C IoT Provisioning Client and how to use them. @@ -25,5 +25,5 @@ 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. -[azure_sdk_for_c_contributing]: ../../../CONTRIBUTING.md +[azure_sdk_for_c_contributing]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md [azure_sdk_for_c_license]: https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE diff --git a/sdk/docs/platform/README.md b/sdk/docs/platform/README.md index d1bec0d2aa..175eada359 100644 --- a/sdk/docs/platform/README.md +++ b/sdk/docs/platform/README.md @@ -36,6 +36,6 @@ 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. -[azure_sdk_for_c_contributing]: ../../../CONTRIBUTING.md +[azure_sdk_for_c_contributing]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md [azure_sdk_for_c_license]: https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE [azure_sdk_cmake_options]: https://github.com/Azure/azure-sdk-for-c/blob/master/README.md#cmake-options diff --git a/sdk/docs/storage/README.md b/sdk/docs/storage/README.md index 2c398df50f..310e67d8b1 100644 --- a/sdk/docs/storage/README.md +++ b/sdk/docs/storage/README.md @@ -81,18 +81,18 @@ Azure SDK for Embedded C is licensed under the [MIT][azure_sdk_for_c_license] li [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_contributing_developer_guide]: ../../../CONTRIBUTING.md#developer-guide -[azure_sdk_for_c_contributing_pull_requests]: ../../../CONTRIBUTING.md#pull-requests +[azure_sdk_for_c_contributing]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md +[azure_sdk_for_c_contributing_developer_guide]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md#developer-guide +[azure_sdk_for_c_contributing_pull_requests]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md#pull-requests [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 +[azure_sdk_for_c_license]: https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE +[azure_sdk_for_c_readme]: https://github.com/Azure/azure-sdk-for-c/blob/master/README.md +[azure_sdk_for_c_readme_getting_started]:https://github.com/Azure/azure-sdk-for-c/blob/master/README.md#getting-started-using-the-sdk +[samples_storage_blobs_readme]: https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/storage/blobs/README.md +[docs_platform_readme]: https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/platform/README.md +[storage_access_control_sas]: https://docs.microsoft.com/rest/api/storageservices/delegate-access-with-shared-access-signature +[storage_account_create]: https://docs.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-portal +[storage_blobs]: https://docs.microsoft.com/azure/storage/blobs/storage-blobs-overview [storage_docs]: https://docs.microsoft.com/azure/storage/ -[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 +[storage_rate_limits]: https://docs.microsoft.com/azure/storage/blobs/scalability-targets +[storage_overview]: https://docs.microsoft.com/azure/storage/blobs/storage-blobs-introduction diff --git a/sdk/samples/core/README.md b/sdk/samples/core/README.md index 0c17f7e85f..27e3e9244c 100644 --- a/sdk/samples/core/README.md +++ b/sdk/samples/core/README.md @@ -28,6 +28,6 @@ This document explains samples and how to use them. This project welcomes contributions and suggestions. Find [more contributing][SDK_README_CONTRIBUTING] details here. -[SDK_README_CONTRIBUTING]: ../../../CONTRIBUTING.md +[SDK_README_CONTRIBUTING]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-c%2Fsdk%2Fcore%2Fcore%2Fsamples%2FREADME.png) diff --git a/sdk/samples/iot/README.md b/sdk/samples/iot/README.md index b16840b98a..95437d30f7 100644 --- a/sdk/samples/iot/README.md +++ b/sdk/samples/iot/README.md @@ -47,13 +47,13 @@ More detailed step-by-step guides on how to run an IoT Hub Client sample from sc To run the samples, ensure you have the following programs and tools installed on your system: -- Have an [Azure account](https://azure.microsoft.com/en-us/) created. -- Have an [Azure IoT Hub](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-create-through-portal) created. -- Have an [Azure IoT Hub Device Provisioning Service (DPS)](https://docs.microsoft.com/en-us/azure/iot-dps/quick-setup-auto-provision) created if running a DPS sample: +- Have an [Azure account](https://azure.microsoft.com/) created. +- Have an [Azure IoT Hub](https://docs.microsoft.com/azure/iot-hub/iot-hub-create-through-portal) created. +- Have an [Azure IoT Hub Device Provisioning Service (DPS)](https://docs.microsoft.com/azure/iot-dps/quick-setup-auto-provision) created if running a DPS sample: *Executables:* `paho_iot_provisioning_sample`, `paho_iot_provisioning_sas_sample` -- Have the most recent version of [Azure IoT Explorer](https://github.com/Azure/azure-iot-explorer/releases) installed (more instructions can be found [here](https://docs.microsoft.com/en-us/azure/iot-pnp/howto-use-iot-explorer)) and connected to your Azure IoT Hub if running a Plug and Play sample: +- Have the most recent version of [Azure IoT Explorer](https://github.com/Azure/azure-iot-explorer/releases) installed (more instructions can be found [here](https://docs.microsoft.com/azure/iot-pnp/howto-use-iot-explorer)) and connected to your Azure IoT Hub if running a Plug and Play sample: *Executables:* `paho_iot_hub_pnp_sample`, `paho_iot_hub_pnp_component_sample` @@ -69,10 +69,10 @@ To run the samples, ensure you have the following programs and tools installed o sudo apt-get install build-essential # make and gcc sudo apt-get install curl unzip tar pkg-config ``` - + Windows: - - Have [Microsoft Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) installed with [C and C++ support](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=vs-2019). + - Have [Microsoft Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) installed with [C and C++ support](https://docs.microsoft.com/cpp/build/vscpp-step-0-installation?view=vs-2019).

@@ -595,7 +595,7 @@ The resulting thumbprint will be placed in `fingerprint.txt` and the generated p
Instructions to run a Hub Certificate sample:

-1. In your Azure IoT Hub, add a new device using a self-signed certificate. See [here](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-security-x509-get-started#create-an-x509-device-for-your-iot-hub) for further instruction, with one exception--**DO NOT** select X.509 CA Signed as the authentication type. Select **X.509 Self-Signed**. +1. In your Azure IoT Hub, add a new device using a self-signed certificate. See [here](https://docs.microsoft.com/azure/iot-hub/iot-hub-security-x509-get-started#create-an-x509-device-for-your-iot-hub) for further instruction, with one exception--**DO NOT** select X.509 CA Signed as the authentication type. Select **X.509 Self-Signed**. For the Thumbprint, use the recently generated fingerprint, which has been placed in the file `fingerprint.txt`. @@ -639,7 +639,7 @@ The resulting thumbprint will be placed in `fingerprint.txt` and the generated p

Instructions to run a Hub SAS sample:

-1. In your Azure IoT Hub, add a new device using a symmetric key. See [here](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-create-through-portal#register-a-new-device-in-the-iot-hub) for further instruction. +1. In your Azure IoT Hub, add a new device using a symmetric key. See [here](https://docs.microsoft.com/azure/iot-hub/iot-hub-create-through-portal#register-a-new-device-in-the-iot-hub) for further instruction. 2. Set the following environment variables: @@ -679,7 +679,7 @@ The resulting thumbprint will be placed in `fingerprint.txt` and the generated p

Instructions to run a Provisioning Certificate sample:

-1. In your Azure IoT Hub DPS, add a new individual device enrollment using the recently generated `device_ec_cert.pem` file. See [here](https://docs.microsoft.com/en-us/azure/iot-dps/quick-create-simulated-device-x509#create-a-device-enrollment-entry-in-the-portal) for further instruction. After creation, the Registration ID of your device should appear as `paho-sample-device1` in the Individual Enrollments tab. +1. In your Azure IoT Hub DPS, add a new individual device enrollment using the recently generated `device_ec_cert.pem` file. See [here](https://docs.microsoft.com/azure/iot-dps/quick-create-simulated-device-x509#create-a-device-enrollment-entry-in-the-portal) for further instruction. After creation, the Registration ID of your device should appear as `paho-sample-device1` in the Individual Enrollments tab. 2. Set the following environment variables: @@ -716,7 +716,7 @@ The resulting thumbprint will be placed in `fingerprint.txt` and the generated p

Instructions to run a Provisioning SAS sample:

-1. In your Azure IoT Hub DPS, add a new individual device enrollment using a symmetric key. See [here](https://docs.microsoft.com/en-us/azure/iot-dps/quick-create-simulated-device-symm-key#create-a-device-enrollment-entry-in-the-portal) for further instruction. After creation, the Registration ID of your device will appear in the Individual Enrollments tab. +1. In your Azure IoT Hub DPS, add a new individual device enrollment using a symmetric key. See [here](https://docs.microsoft.com/azure/iot-dps/quick-create-simulated-device-symm-key#create-a-device-enrollment-entry-in-the-portal) for further instruction. After creation, the Registration ID of your device will appear in the Individual Enrollments tab. 2. Set the following environment variables: @@ -798,8 +798,8 @@ Start using the Azure Embedded C SDK IoT Clients in your solutions! - A general overview of the Embedded C SDK and additional background on running samples can be found in the [Azure SDK for Embedded C README](https://github.com/Azure/azure-sdk-for-c#azure-sdk-for-embedded-c). - More SDK details pertaining to the Azure IoT Client library can be found in the [Azure IoT Client README](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot#azure-iot-clients). - The [Azure IoT Client MQTT State Machine](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md) provides a high-level architecture and API information. -- For extensive documentation on Azure IoT Hub, see the [Microsoft API reference documentation](https://docs.microsoft.com/en-us/azure/iot-hub/about-iot-hub). -- For extensive documentation on Azure IoT Hub Device Provisioning Service, see the [Microsoft API reference documentation](https://docs.microsoft.com/en-us/azure/iot-dps/). +- For extensive documentation on Azure IoT Hub, see the [Microsoft API reference documentation](https://docs.microsoft.com/azure/iot-hub/about-iot-hub). +- For extensive documentation on Azure IoT Hub Device Provisioning Service, see the [Microsoft API reference documentation](https://docs.microsoft.com/azure/iot-dps/). ## Troubleshooting diff --git a/sdk/samples/iot/docs/how_to_iot_hub_esp8266_nodemcu.md b/sdk/samples/iot/docs/how_to_iot_hub_esp8266_nodemcu.md index fcfd555f14..277e6c4749 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_esp8266_nodemcu.md +++ b/sdk/samples/iot/docs/how_to_iot_hub_esp8266_nodemcu.md @@ -21,16 +21,15 @@ _The following was run on an Ubuntu Desktop 20.04 environment, with Arduino IDE ## Prerequisites -- Have an [Azure account](https://azure.microsoft.com/en-us/) created. -- Have an [Azure IoT Hub](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-create-through-portal) created. +- Have an [Azure account](https://azure.microsoft.com/) created. +- Have an [Azure IoT Hub](https://docs.microsoft.com/azure/iot-hub/iot-hub-create-through-portal) created. - Have a logical device created in your Azure IoT Hub using the authentication type "Symmetric Key". - Have the latest [Arduino IDE](https://www.arduino.cc/en/Main/Software) installed. - - Use one of the two: - Graphical user interface to Azure IoT: [azure-iot-explorer](https://github.com/Azure/azure-iot-explorer/releases). - - [Azure Command Line Interface utility](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-apt?view=azure-cli-latest#install-with-one-command) and the IoT extension + - [Azure Command Line Interface utility](https://docs.microsoft.com/cli/azure/install-azure-cli-apt?view=azure-cli-latest#install-with-one-command) and the IoT extension ```shell diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md index 4639104e8c..ca5349fb4b 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md +++ b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md @@ -38,8 +38,8 @@ _The following was run on an Ubuntu Desktop 18.04 environment, but it also works To run the samples, ensure you have the following programs and tools installed on your system: -- Have an [Azure account](https://azure.microsoft.com/en-us/) created. -- Have an [Azure IoT Hub](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-create-through-portal) created. +- Have an [Azure account](https://azure.microsoft.com/) created. +- Have an [Azure IoT Hub](https://docs.microsoft.com/azure/iot-hub/iot-hub-create-through-portal) created. - Have the following setup: build environment, tools, [Git](https://git-scm.com/download/linux), and OpenSSL. These commands can be run from any directory. ```bash @@ -165,12 +165,12 @@ To run the samples, ensure you have the following programs and tools installed o 2. Create a logical device. - In your Azure IoT Hub, add a new device using a self-signed certificate. See [here](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-security-x509-get-started#create-an-x509-device-for-your-iot-hub) to get started, but use the values below: + In your Azure IoT Hub, add a new device using a self-signed certificate. See [here](https://docs.microsoft.com/azure/iot-hub/iot-hub-security-x509-get-started#create-an-x509-device-for-your-iot-hub) to get started, but use the values below: - **Device ID**: testdevice-x509 - **Authentication type**: X.509 Self-Signed - **Primary and Secondary Thumbprint**: Use the recently generated fingerprint, which has been placed in the file `fingerprint.txt`. - + Select "Save". 3. Set the remaining environment variables needed for the samples. diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md index c8c511bfc2..aedeee7aef 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md +++ b/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md @@ -38,9 +38,9 @@ NOTE: For simplicity in this instruction set, all repository downloads will be p To run the samples, ensure you have the following programs and tools installed on your system: -- Have an [Azure account](https://azure.microsoft.com/en-us/) created. -- Have an [Azure IoT Hub](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-create-through-portal) created. -- Have [Microsoft Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) installed with [C and C++ support](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=vs-2019). +- Have an [Azure account](https://azure.microsoft.com/) created. +- Have an [Azure IoT Hub](https://docs.microsoft.com/azure/iot-hub/iot-hub-create-through-portal) created. +- Have [Microsoft Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) installed with [C and C++ support](https://docs.microsoft.com/cpp/build/vscpp-step-0-installation?view=vs-2019). - Have [Git](https://git-scm.com/download/win) for Windows installed. - Have the latest version of [CMake](https://cmake.org/download) installed. @@ -167,7 +167,7 @@ To run the samples, ensure you have the following programs and tools installed o 2. Create a logical device. - In your Azure IoT Hub, add a new device using a self-signed certificate. See [here](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-security-x509-get-started#create-an-x509-device-for-your-iot-hub) to get started, but use the values below: + In your Azure IoT Hub, add a new device using a self-signed certificate. See [here](https://docs.microsoft.com/azure/iot-hub/iot-hub-security-x509-get-started#create-an-x509-device-for-your-iot-hub) to get started, but use the values below: - **Device ID**: paho-sample-device1 - **Authentication type**: X.509 Self-Signed diff --git a/sdk/samples/storage/blobs/README.md b/sdk/samples/storage/blobs/README.md index 3f93657787..4b291215db 100644 --- a/sdk/samples/storage/blobs/README.md +++ b/sdk/samples/storage/blobs/README.md @@ -50,14 +50,14 @@ 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. -[azure_sdk_for_c_contributing]: ../../../../CONTRIBUTING.md +[azure_sdk_for_c_contributing]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md [azure_sdk_for_c_license]: https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE [BLOB_SDK_README]: https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/storage [SDK_README_CONTRIBUTING]:https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/storage#contributing [SDK_README_GETTING_STARTED]: https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/storage#getting-started [SDK_README_KEY_CONCEPTS]: https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/storage#key-concepts -[samples_basic]: src/blobs_client_example.c -[storageblob_rest]: https://docs.microsoft.com/en-us/rest/api/storageservices/blob-service-rest-api +[samples_basic]: https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/storage/blobs/src/blobs_client_example.c +[storageblob_rest]: https://docs.microsoft.com/rest/api/storageservices/blob-service-rest-api [error_codes]: https://docs.microsoft.com/rest/api/storageservices/blob-service-error-codes ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-c%2Fsdk%2Fstorage%2Fblobs%2Fsrc%2Fsamples%2FREADME.png)