Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/platform_requirements.md

raw
1 # platform
2
3
4 ## Overview
5
6 This document specifies the **platform** adapter for the Azure IoT C SDK. The purpose of _platform_ is
7 to provide any global init and de-init that may be required, such as `WSAStartup` and `WSACleanup`
8 for Windows. It also provides the SDK with the proper TLSIO adapter via `platform_get_default_tlsio`.
9
10 Although the platform adapter provides a mechanism for performing global init and de-init, device
11 implementers
12 may find it makes more sense to perform these operations outside of the scope of the Azure IoT SDK.
13 In that case, the `platform_init` and `platform_deinit` calls may be left empty.
14
15 ### References
16 [Azure IoT porting guide](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/porting_guide.md)<br/>
17 [platform.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/platform.h)<br/>
18 [xio.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/xio.h)
19
20
21 ### Exposed API
22 The platform adapter must implement 3 of the 4 functions defined in
23 [platform.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/platform.h):
24 `platform_init`, `platform_deinit`, and `platform_get_default_tlsio`. The fourth function,
25 `platform_get_platform_info`, is not used by the SDK and my be omitted.
26
27 ### platform_init
28
29 The `platform_init` call performs any global initialization necessary for a particular platform.
30
31 ```c
32 int platform_init();
33 ```
34
35 **SRS_PLATFORM_30_000: [** The `platform_init` call shall perform any global initialization needed by the platform and return 0 on success. **]**
36
37 **SRS_PLATFORM_30_001: [** On failure, `platform_init` shall return a non-zero value. **]**
38
39
40 ### platform_deinit
41
42 The `platform_deinit` call performs any global initialization necessary for a particular platform.
43
44 ```c
45 void platform_deinit();
46 ```
47
48 **SRS_PLATFORM_30_010: [** The `platform_deinit` call shall perform any global deinitialization needed by the platform. **]**
49
50
51 ### platform_get_default_tlsio
52
53 This call returns the `IO_INTERFACE_DESCRIPTION*` for the platform's tlsio as defined in
54 [xio.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/xio.h).
55
56
57
58 ```c
59 const IO_INTERFACE_DESCRIPTION* platform_get_default_tlsio(void);
60 ```
61
62 **SRS_PLATFORM_30_020: [** The `platform_get_default_tlsio` call shall return the `IO_INTERFACE_DESCRIPTION*` for the platform's tlsio. **]**