Azure
/
azure-c-shared-utility
зеркало из https://github.com/Azure/azure-c-shared-utility.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Formatting fixes (add whitespace only)

This commit is contained in:
Roy Sprowl 2017-03-29 10:18:18 -07:00
Родитель 5c16a6bfc0
Коммит 8c9173f4ad
42 изменённых файлов: 2009 добавлений и 1123 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

4
devdoc/agenttime_requirements.md
Просмотреть файл

@ -3,10 +3,10 @@ AgentTime
##Overview
AgentTime exports platform independent time related functions. It is a platform abstration and it requires a specific implementation for each platform.
AgentTime exports platform independent time related functions. It is a platform abstraction and it requires a specific implementation for each platform.
Most of the times these functions can simply call the C standard time functions.
**SRS_AGENT_TIME_99_001: [** AGENT_TIME shall have the following interface**]**
**SRS_AGENT_TIME_99_001: [** AGENT_TIME shall have the following interface **]**
```c
/* same functionality as time() of standard C function */
time_t get_time(time_t* p);

47
devdoc/base64_requirements.md
Просмотреть файл

@ -1,14 +1,14 @@
Base64 Requirements
================
##Overview
## Overview
This module is used to encode a BUFFER using the standard base64 encoding stream.
##References
## References
[IETF RFC 4648](https://tools.ietf.org/html/rfc4648)
##Exposed API
## Exposed API
```c
extern STRING_HANDLE Base64_Encode(BUFFER_HANDLE input);
@ -16,34 +16,45 @@ extern STRING_HANDLE Base64_Encode_Bytes(const unsigned char* source, size_t siz
extern BUFFER_HANDLE Base64_Decoder(const char* source);
```
###Base64_Encode
### Base64_Encode
```c
extern STRING_HANDLE Base64_Encode(BUFFER_HANDLE input);
```
Base64_Encode takes as a parameter a pointer to BUFFER, input.
**SRS_BASE64_06_001: [**If input is NULL then Base64_Encode shall return NULL.**]** The size of the BUFFER pointed to by input MAY be zero.
**SRS_BASE64_06_006: [**If when allocating memory to produce the encoding a failure occurs then Base64_Encode shall return NULL.**]**
**SRS_BASE64_06_007: [**Otherwise Base64_Encode shall return a pointer to STRING, that string contains the base 64 encoding of input.**]**
**SRS_BASE64_06_001: [** If input is NULL then Base64_Encode shall return NULL. **]**
The size of the BUFFER pointed to by input MAY be zero.
**SRS_BASE64_06_006: [** If when allocating memory to produce the encoding a failure occurs then Base64_Encode shall return NULL. **]**
**SRS_BASE64_06_007: [** Otherwise Base64_Encode shall return a pointer to STRING, that string contains the base 64 encoding of input. **]**
This encoding of input shall NOT contain embedded line feeds.
###Base64_Encode_Bytes
### Base64_Encode_Bytes
```c
extern STRING_HANDLE Base64_Encode_Bytes(const unsigned char* source, size_t size);
```
Base64_Encode_Bytes shall produce a STRING_HANDLE containing the base64 encoding of the buffer pointed to by source, having the size as given by parameter size.
**SRS_BASE64_02_001: [**If source is NULL then Base64_Encode_Bytes shall return NULL.**]**
**SRS_BASE64_02_002: [**If source is not NULL and size is zero, then Base64_Encode_Bytes shall produce an empty STRING_HANDLE.**]**
**SRS_BASE64_02_003: [**Otherwise, Base64_Encode_Bytes shall produce a STRING_HANDLE containing the Base64 representation of the buffer.**]**
**SRS_BASE64_02_004: [**In case of any errors, Base64_Encode_Bytes shall return NULL.**]**
###Base64_Decoder
**SRS_BASE64_02_001: [** If source is NULL then Base64_Encode_Bytes shall return NULL. **]**
**SRS_BASE64_02_002: [** If source is not NULL and size is zero, then Base64_Encode_Bytes shall produce an empty STRING_HANDLE. **]**
**SRS_BASE64_02_003: [** Otherwise, Base64_Encode_Bytes shall produce a STRING_HANDLE containing the Base64 representation of the buffer. **]**
**SRS_BASE64_02_004: [** In case of any errors, Base64_Encode_Bytes shall return NULL. **]**
### Base64_Decoder
```c
extern BUFFER_HANDLE Base64_Decoder(const char* source);
```
**SRS_BASE64_06_008: [**If source is NULL then Base64_Decoder shall return NULL.**]**
**SRS_BASE64_06_009: [**If the string pointed to by source is zero length then the handle returned shall refer to a zero length buffer.**]**
**SRS_BASE64_06_010: [**If there is any memory allocation failure during the decode then Base64_Decoder shall return NULL.**]**
**SRS_BASE64_06_011: [**If the source string has an invalid length for a base 64 encoded string then Base64_Decoder shall return NULL.**]**
**SRS_BASE64_06_008: [** If source is NULL then Base64_Decoder shall return NULL. **]**
**SRS_BASE64_06_009: [** If the string pointed to by source is zero length then the handle returned shall refer to a zero length buffer. **]**
**SRS_BASE64_06_010: [** If there is any memory allocation failure during the decode then Base64_Decoder shall return NULL. **]**
**SRS_BASE64_06_011: [** If the source string has an invalid length for a base 64 encoded string then Base64_Decoder shall return NULL. **]**

140
devdoc/buffer_requirements.md
Просмотреть файл

@ -1,11 +1,11 @@
BUFFER Requirements
================
##Overview
## Overview
The BUFFER object encapsulastes a unsigned char* variable.
##Exposed API
## Exposed API
```c
typedef void* BUFFER_HANDLE;
@ -26,116 +26,140 @@ extern size_t BUFFER_length(BUFFER_HANDLE handle);
extern BUFFER_HANDLE BUFFER_clone(BUFFER_HANDLE handle);
```
###BUFFER_new
### BUFFER_new
```c
BUFFER_HANDLE BUFFER_new(void)
```
**SRS_BUFFER_07_001: [**BUFFER_new shall allocate a BUFFER_HANDLE that will contain a NULL unsigned char*.**]**
###BUFFER_create
**SRS_BUFFER_07_001: [** BUFFER_new shall allocate a BUFFER_HANDLE that will contain a NULL unsigned char*. **]**
### BUFFER_create
```c
extern BUFFER_HANDLE BUFFER_create(const unsigned char* source, size_t size);
```
BUFFER_create creates a new buffer from the memory at source, having size "size".
**SRS_BUFFER_02_001: [**If source is NULL then BUFFER_create shall return NULL.**]**
**SRS_BUFFER_02_002: [**Otherwise, BUFFER_create shall allocate memory to hold size bytes and shall copy from source size bytes into the newly allocated memory.**]**
**SRS_BUFFER_02_003: [**If allocating memory fails, then BUFFER_create shall return NULL.**]**
**SRS_BUFFER_02_004: [**Otherwise, BUFFER_create shall return a non-NULL handle.**]**
###BUFFER_delete
**SRS_BUFFER_02_001: [** If source is NULL then BUFFER_create shall return NULL. **]**
**SRS_BUFFER_02_002: [** Otherwise, BUFFER_create shall allocate memory to hold size bytes and shall copy from source size bytes into the newly allocated memory. **]**
**SRS_BUFFER_02_003: [** If allocating memory fails, then BUFFER_create shall return NULL. **]**
**SRS_BUFFER_02_004: [** Otherwise, BUFFER_create shall return a non-NULL handle. **]**
### BUFFER_delete
```c
void BUFFER_delete(BUFFER_HANDLE handle)
```
**SRS_BUFFER_07_003: [**BUFFER_delete shall delete the data associated with the BUFFER_HANDLE along with the Buffer.**]**
**SRS_BUFFER_07_004: [**BUFFER_delete shall not delete any BUFFER_HANDLE that is NULL.**]**
**SRS_BUFFER_07_003: [** BUFFER_delete shall delete the data associated with the BUFFER_HANDLE along with the Buffer. **]**
###BUFFER_pre_build
```c
**SRS_BUFFER_07_004: [** BUFFER_delete shall not delete any BUFFER_HANDLE that is NULL. **]**
### BUFFER_pre_build
```c
int BUFFER_pre_build(BUFFER_HANDLE handle, size_t size)
```
**SRS_BUFFER_07_005: [**BUFFER_pre_build allocates size_t bytes of BUFFER_HANDLE and returns zero on success.**]**
**SRS_BUFFER_07_006: [**If handle is NULL or size is 0 then BUFFER_pre_build shall return a nonzero value.**]**
**SRS_BUFFER_07_007: [**BUFFER_pre_build shall return nonzero if the buffer has been previously allocated and is not NULL.**]**
**SRS_BUFFER_07_013: [**BUFFER_pre_build shall return nonzero if any error is encountered.**]**
**SRS_BUFFER_07_005: [** BUFFER_pre_build allocates size_t bytes of BUFFER_HANDLE and returns zero on success. **]**
###BUFFER_build
```c
**SRS_BUFFER_07_006: [** If handle is NULL or size is 0 then BUFFER_pre_build shall return a nonzero value. **]**
**SRS_BUFFER_07_007: [** BUFFER_pre_build shall return nonzero if the buffer has been previously allocated and is not NULL. **]**
**SRS_BUFFER_07_013: [** BUFFER_pre_build shall return nonzero if any error is encountered. **]**
### BUFFER_build
```c
int BUFFER_build(BUFFER_HANDLE handle, const unsigned char* source, size_t size)
```
**SRS_BUFFER_07_008: [**BUFFER_build allocates size_t bytes, copies the unsigned char* into the buffer and returns zero on success.**]**
**SRS_BUFFER_07_009: [**BUFFER_build shall return nonzero if handle is NULL **]**
**SRS_BUFFER_01_001: [**If size is positive and source is NULL, BUFFER_build shall return nonzero**]**
**SRS_BUFFER_01_002: [**The size argument can be zero, in which case the underlying buffer held by the buffer instance shall be freed.**]**
**SRS_BUFFER_01_003: [**If size is zero, source can be NULL.**]**
**SRS_BUFFER_07_010: [**BUFFER_build shall return nonzero if any error is encountered.**]**
**SRS_BUFFER_07_011: [**BUFFER_build shall overwrite previous contents if the buffer has been previously allocated.**]**
**SRS_BUFFER_07_008: [** BUFFER_build allocates size_t bytes, copies the unsigned char* into the buffer and returns zero on success. **]**
###BUFFER_unbuild
**SRS_BUFFER_07_009: [** BUFFER_build shall return nonzero if handle is NULL **]**
**SRS_BUFFER_01_001: [** If size is positive and source is NULL, BUFFER_build shall return nonzero **]**
**SRS_BUFFER_01_002: [** The size argument can be zero, in which case the underlying buffer held by the buffer instance shall be freed. **]**
**SRS_BUFFER_01_003: [** If size is zero, source can be NULL. **]**
**SRS_BUFFER_07_010: [** BUFFER_build shall return nonzero if any error is encountered. **]**
**SRS_BUFFER_07_011: [** BUFFER_build shall overwrite previous contents if the buffer has been previously allocated. **]**
### BUFFER_unbuild
```c
int BUFFER_unbuild(BUFFER_HANDLE b)
```
**SRS_BUFFER_07_012: [**BUFFER_unbuild shall clear the underlying unsigned char* data associated with the BUFFER_HANDLE this will return zero on success.**]**
**SRS_BUFFER_07_014: [**BUFFER_unbuild shall return a nonzero value if BUFFER_HANDLE is NULL.**]**
**SRS_BUFFER_07_015: [**BUFFER_unbuild shall return a nonzero value if the unsigned char* referenced by BUFFER_HANDLE is NULL.**]**
**SRS_BUFFER_07_012: [** BUFFER_unbuild shall clear the underlying unsigned char* data associated with the BUFFER_HANDLE this will return zero on success. **]**
###BUFFER_enlarge
**SRS_BUFFER_07_014: [** BUFFER_unbuild shall return a nonzero value if BUFFER_HANDLE is NULL. **]**
**SRS_BUFFER_07_015: [** BUFFER_unbuild shall return a nonzero value if the unsigned char* referenced by BUFFER_HANDLE is NULL. **]**
### BUFFER_enlarge
```c
int BUFFER_enlarge(BUFFER_HANDLE handle, size_t enlargeSize)
```
**SRS_BUFFER_07_016: [**BUFFER_enlarge shall increase the size of the unsigned char* referenced by BUFFER_HANDLE.**]**
**SRS_BUFFER_07_017: [**BUFFER_enlarge shall return a nonzero result if any parameters are NULL or zero.**]**
**SRS_BUFFER_07_018: [**BUFFER_enlarge shall return a nonzero result if any error is encountered.**]**
###BUFFER_content
**SRS_BUFFER_07_016: [** BUFFER_enlarge shall increase the size of the unsigned char* referenced by BUFFER_HANDLE. **]**
**SRS_BUFFER_07_017: [** BUFFER_enlarge shall return a nonzero result if any parameters are NULL or zero. **]**
**SRS_BUFFER_07_018: [** BUFFER_enlarge shall return a nonzero result if any error is encountered. **]**
### BUFFER_content
```c
int BUFFER_content(BUFFER_HANDLE handle, unsigned char** content)
```
**SRS_BUFFER_07_019: [**BUFFER_content shall return the data contained within the BUFFER_HANDLE.**]**
**SRS_BUFFER_07_020: [**If the handle and/or content*is NULL BUFFER_content shall return nonzero.**]**
###BUFFER_size
**SRS_BUFFER_07_019: [** BUFFER_content shall return the data contained within the BUFFER_HANDLE. **]**
**SRS_BUFFER_07_020: [** If the handle and/or content*is NULL BUFFER_content shall return nonzero. **]**
### BUFFER_size
```c
int BUFFER_size(BUFFER_HANDLE b, size_t* size)
```
**SRS_BUFFER_07_021: [**BUFFER_size shall place the size of the associated buffer in the size variable and return zero on success.**]**
**SRS_BUFFER_07_022: [**BUFFER_size shall return a nonzero value for any error that is encountered.**]**
###BUFFER_append
**SRS_BUFFER_07_021: [** BUFFER_size shall place the size of the associated buffer in the size variable and return zero on success. **]**
**SRS_BUFFER_07_022: [** BUFFER_size shall return a nonzero value for any error that is encountered. **]**
### BUFFER_append
```c
int BUFFER_append(BUFFER_HANDLE handle1, BUFFER_HANDLE handle2)
```
**SRS_BUFFER_07_024: [**BUFFER_append concatenates b2 onto b1 without modifying b2 and shall return zero on success.**]**
**SRS_BUFFER_07_023: [**BUFFER_append shall return a nonzero upon any error that is encountered.**]**
**SRS_BUFFER_07_024: [** BUFFER_append concatenates b2 onto b1 without modifying b2 and shall return zero on success. **]**
###BUFFER_prepend
**SRS_BUFFER_07_023: [** BUFFER_append shall return a nonzero upon any error that is encountered. **]**
### BUFFER_prepend
```c
int BUFFER_prepend(BUFFER_HANDLE handle1, BUFFER_HANDLE handle2)
```
**SRS_BUFFER_01_004: [** BUFFER_prepend concatenates handle1 onto handle2 without modifying handle1 and shall return zero on success. **]**
**SRS_BUFFER_01_004: [** BUFFER_prepend concatenates handle1 onto handle2 without modifying handle1 and shall return zero on success. **]**
**SRS_BUFFER_01_005: [** BUFFER_prepend shall return a non-zero upon value any error that is encountered. **]**
###BUFFER_u_char
### BUFFER_u_char
```c
unsigned char* BUFFER_u_char(BUFFER_HANDLE handle)
```
**SRS_BUFFER_07_025: [**BUFFER_u_char shall return a pointer to the underlying unsigned char*.**]**
**SRS_BUFFER_07_026: [**BUFFER_u_char shall return NULL for any error that is encountered.**]**
###BUFFER_length
**SRS_BUFFER_07_025: [** BUFFER_u_char shall return a pointer to the underlying unsigned char*. **]**
**SRS_BUFFER_07_026: [** BUFFER_u_char shall return NULL for any error that is encountered. **]**
### BUFFER_length
```c
size_t BUFFER_length(BUFFER_HANDLE handle)
```
**SRS_BUFFER_07_027: [**BUFFER_length shall return the size of the underlying buffer.**]**
**SRS_BUFFER_07_028: [**BUFFER_length shall return zero for any error that is encountered.**]**
**SRS_BUFFER_07_027: [** BUFFER_length shall return the size of the underlying buffer. **]**
**SRS_BUFFER_07_028: [** BUFFER_length shall return zero for any error that is encountered. **]**

8
devdoc/condition_requirements.md
Просмотреть файл

@ -54,7 +54,7 @@ extern COND_RESULT Condition_Wait(COND_HANDLE handle, LOCK_HANDLE lock, int tim
extern void Condition_Deinit(COND_HANDLE handle);
```
### Condition_Init
### Condition_Init
```C
extern COND_HANDLE Condition_Init(void);
```
@ -64,7 +64,7 @@ extern COND_HANDLE Condition_Init(void);
**SRS_CONDITION_18_008: [** `Condition_Init` shall return `NULL` if it fails to allocate the `CONDITION_HANDLE` **]**
### Condition_Post
### Condition_Post
```C
extern COND_RESULT Condition_Post(COND_HANDLE handle);
```
@ -74,7 +74,7 @@ extern COND_RESULT Condition_Post(COND_HANDLE handle);
**SRS_CONDITION_18_001: [** `Condition_Post` shall return `COND_INVALID_ARG` if `handle` is `NULL` **]**
### Condition_Wait
### Condition_Wait
```C
extern COND_RESULT Condition_Wait(COND_HANDLE handle, LOCK_HANDLE lock, int timeout_milliseconds);
```
@ -94,7 +94,7 @@ extern COND_RESULT Condition_Wait(COND_HANDLE handle, LOCK_HANDLE lock, int tim
**SRS_CONDITION_18_013: [** `Condition_Wait` shall accept relative timeouts **]**
### Condition_Deinit
### Condition_Deinit
```C
extern void Condition_Deinit(COND_HANDLE handle);
```

110
devdoc/connectionstringparser_requirements.md
Просмотреть файл

@ -1,13 +1,13 @@
#connectionstringparser requirements
====================================
##Overview
## Overview
connection_parser is module that parses key/value pairs from a connection string.
The format of the connection string is:
[key1]=[value1];[key2]=[value2]; ...
##Exposed API
## Exposed API
```c
extern MAP_HANDLE connectionstringparser_parse_from_char(const char* connection_string);
@ -16,67 +16,97 @@ extern int connectionstringparser_splitHostName_from_char(const char* hostName,
extern int connectionstringparser_splitHostName(STRING_HANDLE hostNameString, STRING_HANDLE nameString, STRING_HANDLE suffixString);
```
###connectionstringparser_parse
### connectionstringparser_parse
```c
extern MAP_HANDLE connectionstringparser_parse(STRING_HANDLE connection_string);
```
**SRS_CONNECTIONSTRINGPARSER_01_001: [**connectionstringparser_parse shall parse all key value pairs from the connection_string passed in as argument and return a new map that holds the key/value pairs.**]**
**SRS_CONNECTIONSTRINGPARSER_01_018: [**If creating the result map fails, then connectionstringparser_parse shall return NULL.**]**
**SRS_CONNECTIONSTRINGPARSER_01_002: [**If connection_string is NULL then connectionstringparser_parse shall fail and return NULL.**]**
**SRS_CONNECTIONSTRINGPARSER_01_003: [**connectionstringparser_parse shall create a STRING tokenizer to be used for parsing the connection string, by calling STRING_TOKENIZER_create.**]**
**SRS_CONNECTIONSTRINGPARSER_01_015: [**If STRING_TOKENIZER_create fails, connectionstringparser_parse shall fail and return NULL.**]**
**SRS_CONNECTIONSTRINGPARSER_01_004: [**connectionstringparser_parse shall start scanning at the beginning of the connection string.**]**
**SRS_CONNECTIONSTRINGPARSER_01_016: [**2 STRINGs shall be allocated in order to hold the to be parsed key and value tokens.**]**
**SRS_CONNECTIONSTRINGPARSER_01_017: [**If allocating the STRINGs fails connectionstringparser_parse shall fail and return NULL.**]**
**SRS_CONNECTIONSTRINGPARSER_01_005: [**The following actions shall be repeated until parsing is complete:**]**
**SRS_CONNECTIONSTRINGPARSER_01_006: [**connectionstringparser_parse shall find a token (the key of the key/value pair) delimited by the `=` character, by calling STRING_TOKENIZER_get_next_token.**]**
**SRS_CONNECTIONSTRINGPARSER_01_007: [**If STRING_TOKENIZER_get_next_token fails, parsing shall be considered complete.**]**
**SRS_CONNECTIONSTRINGPARSER_01_008: [**connectionstringparser_parse shall find a token (the value of the key/value pair) delimited by the `;` character, by calling STRING_TOKENIZER_get_next_token.**]**
**SRS_CONNECTIONSTRINGPARSER_01_009: [**If STRING_TOKENIZER_get_next_token fails, connectionstringparser_parse shall fail and return NULL (freeing the allocated result map).**]**
**SRS_CONNECTIONSTRINGPARSER_01_010: [**The key and value shall be added to the result map by using Map_Add.**]**
**SRS_CONNECTIONSTRINGPARSER_01_011: [**The C strings for the key and value shall be extracted from the previously parsed STRINGs by using STRING_c_str.**]**
**SRS_CONNECTIONSTRINGPARSER_01_019: [**If the key length is zero then connectionstringparser_parse shall fail and return NULL (freeing the allocated result map).**]**
**SRS_CONNECTIONSTRINGPARSER_01_012: [**If Map_Add fails connectionstringparser_parse shall fail and return NULL (freeing the allocated result map).**]**
**SRS_CONNECTIONSTRINGPARSER_01_013: [**If STRING_c_str fails then connectionstringparser_parse shall fail and return NULL (freeing the allocated result map).**]**
**SRS_CONNECTIONSTRINGPARSER_01_014: [**After the parsing is complete the previously allocated STRINGs and STRING tokenizer shall be freed by calling STRING_TOKENIZER_destroy.**]**
**SRS_CONNECTIONSTRINGPARSER_01_001: [** connectionstringparser_parse shall parse all key value pairs from the connection_string passed in as argument and return a new map that holds the key/value pairs. **]**
**SRS_CONNECTIONSTRINGPARSER_01_018: [** If creating the result map fails, then connectionstringparser_parse shall return NULL. **]**
**SRS_CONNECTIONSTRINGPARSER_01_002: [** If connection_string is NULL then connectionstringparser_parse shall fail and return NULL. **]**
**SRS_CONNECTIONSTRINGPARSER_01_003: [** connectionstringparser_parse shall create a STRING tokenizer to be used for parsing the connection string, by calling STRING_TOKENIZER_create. **]**
**SRS_CONNECTIONSTRINGPARSER_01_015: [** If STRING_TOKENIZER_create fails, connectionstringparser_parse shall fail and return NULL. **]**
**SRS_CONNECTIONSTRINGPARSER_01_004: [** connectionstringparser_parse shall start scanning at the beginning of the connection string. **]**
**SRS_CONNECTIONSTRINGPARSER_01_016: [** 2 STRINGs shall be allocated in order to hold the to be parsed key and value tokens. **]**
**SRS_CONNECTIONSTRINGPARSER_01_017: [** If allocating the STRINGs fails connectionstringparser_parse shall fail and return NULL. **]**
**SRS_CONNECTIONSTRINGPARSER_01_005: [** The following actions shall be repeated until parsing is complete: **]**
**SRS_CONNECTIONSTRINGPARSER_01_006: [** connectionstringparser_parse shall find a token (the key of the key/value pair) delimited by the `=` character, by calling STRING_TOKENIZER_get_next_token. **]**
**SRS_CONNECTIONSTRINGPARSER_01_007: [** If STRING_TOKENIZER_get_next_token fails, parsing shall be considered complete. **]**
**SRS_CONNECTIONSTRINGPARSER_01_008: [** connectionstringparser_parse shall find a token (the value of the key/value pair) delimited by the `;` character, by calling STRING_TOKENIZER_get_next_token. **]**
**SRS_CONNECTIONSTRINGPARSER_01_009: [** If STRING_TOKENIZER_get_next_token fails, connectionstringparser_parse shall fail and return NULL (freeing the allocated result map). **]**
**SRS_CONNECTIONSTRINGPARSER_01_010: [** The key and value shall be added to the result map by using Map_Add. **]**
**SRS_CONNECTIONSTRINGPARSER_01_011: [** The C strings for the key and value shall be extracted from the previously parsed STRINGs by using STRING_c_str. **]**
**SRS_CONNECTIONSTRINGPARSER_01_019: [** If the key length is zero then connectionstringparser_parse shall fail and return NULL (freeing the allocated result map). **]**
**SRS_CONNECTIONSTRINGPARSER_01_012: [** If Map_Add fails connectionstringparser_parse shall fail and return NULL (freeing the allocated result map). **]**
**SRS_CONNECTIONSTRINGPARSER_01_013: [** If STRING_c_str fails then connectionstringparser_parse shall fail and return NULL (freeing the allocated result map). **]**
**SRS_CONNECTIONSTRINGPARSER_01_014: [** After the parsing is complete the previously allocated STRINGs and STRING tokenizer shall be freed by calling STRING_TOKENIZER_destroy. **]**
###connectionstringparser_parse_from_char
### connectionstringparser_parse_from_char
```c
extern MAP_HANDLE connectionstringparser_parse_from_char(const char* connection_string);
```
**SRS_CONNECTIONSTRINGPARSER_21_020: [**connectionstringparser_parse_from_char shall create a STRING_HANDLE from the connection_string passed in as argument and parse it using the connectionstringparser_parse.**]**
**SRS_CONNECTIONSTRINGPARSER_21_021: [**If connectionstringparser_parse_from_char get error creating a STRING_HANDLE, it shall return NULL.**]**
**SRS_CONNECTIONSTRINGPARSER_21_020: [** connectionstringparser_parse_from_char shall create a STRING_HANDLE from the connection_string passed in as argument and parse it using the connectionstringparser_parse. **]**
**SRS_CONNECTIONSTRINGPARSER_21_021: [** If connectionstringparser_parse_from_char get error creating a STRING_HANDLE, it shall return NULL. **]**
###connectionstringparser_splitHostName_from_char
### connectionstringparser_splitHostName_from_char
```c
extern int connectionstringparser_splitHostName_from_char(const char* hostName, STRING_HANDLE nameString, STRING_HANDLE suffixString);
```
**SRS_CONNECTIONSTRINGPARSER_21_022: [**connectionstringparser_splitHostName_from_char shall split the provided hostName in name and suffix.**]**
**SRS_CONNECTIONSTRINGPARSER_21_023: [**connectionstringparser_splitHostName_from_char shall copy all characters, from the beginning of the hostName to the first `.` to the nameString.**]**
**SRS_CONNECTIONSTRINGPARSER_21_024: [**connectionstringparser_splitHostName_from_char shall copy all characters, from the first `.` to the end of the hostName, to the suffixString.**]**
**SRS_CONNECTIONSTRINGPARSER_21_025: [**If connectionstringparser_splitHostName_from_char get success splitting the hostName, it shall return 0.**]**
**SRS_CONNECTIONSTRINGPARSER_21_026: [**If the hostName is NULL, connectionstringparser_splitHostName_from_char shall return __FAILURE__.**]**
**SRS_CONNECTIONSTRINGPARSER_21_027: [**If the hostName is an empty string, connectionstringparser_splitHostName_from_char shall return __FAILURE__.**]**
**SRS_CONNECTIONSTRINGPARSER_21_028: [**If the nameString is NULL, connectionstringparser_splitHostName_from_char shall return __FAILURE__.**]**
**SRS_CONNECTIONSTRINGPARSER_21_029: [**If the suffixString is NULL, connectionstringparser_splitHostName_from_char shall return __FAILURE__.**]**
**SRS_CONNECTIONSTRINGPARSER_21_030: [**If the hostName is not a valid host name, connectionstringparser_splitHostName_from_char shall return __FAILURE__.**]**
**SRS_CONNECTIONSTRINGPARSER_21_031: [**If connectionstringparser_splitHostName_from_char get error copying the name to the nameString, it shall return __FAILURE__.**]**
**SRS_CONNECTIONSTRINGPARSER_21_032: [**If connectionstringparser_splitHostName_from_char get error copying the suffix to the suffixString, it shall return __FAILURE__.**]**
**SRS_CONNECTIONSTRINGPARSER_21_022: [** connectionstringparser_splitHostName_from_char shall split the provided hostName in name and suffix. **]**
**SRS_CONNECTIONSTRINGPARSER_21_023: [** connectionstringparser_splitHostName_from_char shall copy all characters, from the beginning of the hostName to the first `.` to the nameString. **]**
**SRS_CONNECTIONSTRINGPARSER_21_024: [** connectionstringparser_splitHostName_from_char shall copy all characters, from the first `.` to the end of the hostName, to the suffixString. **]**
**SRS_CONNECTIONSTRINGPARSER_21_025: [** If connectionstringparser_splitHostName_from_char get success splitting the hostName, it shall return 0. **]**
**SRS_CONNECTIONSTRINGPARSER_21_026: [** If the hostName is NULL, connectionstringparser_splitHostName_from_char shall return __FAILURE__. **]**
**SRS_CONNECTIONSTRINGPARSER_21_027: [** If the hostName is an empty string, connectionstringparser_splitHostName_from_char shall return __FAILURE__. **]**
**SRS_CONNECTIONSTRINGPARSER_21_028: [** If the nameString is NULL, connectionstringparser_splitHostName_from_char shall return __FAILURE__. **]**
**SRS_CONNECTIONSTRINGPARSER_21_029: [** If the suffixString is NULL, connectionstringparser_splitHostName_from_char shall return __FAILURE__. **]**
**SRS_CONNECTIONSTRINGPARSER_21_030: [** If the hostName is not a valid host name, connectionstringparser_splitHostName_from_char shall return __FAILURE__. **]**
**SRS_CONNECTIONSTRINGPARSER_21_031: [** If connectionstringparser_splitHostName_from_char get error copying the name to the nameString, it shall return __FAILURE__. **]**
**SRS_CONNECTIONSTRINGPARSER_21_032: [** If connectionstringparser_splitHostName_from_char get error copying the suffix to the suffixString, it shall return __FAILURE__. **]**
###connectionstringparser_splitHostName
### connectionstringparser_splitHostName
```c
extern int connectionstringparser_splitHostName(STRING_HANDLE hostNameString, STRING_HANDLE nameString, STRING_HANDLE suffixString);
```
**SRS_CONNECTIONSTRINGPARSER_21_033: [**connectionstringparser_splitHostName shall convert the hostNameString to a connection_string passed in as argument, and call connectionstringparser_splitHostName_from_char.**]**
**SRS_CONNECTIONSTRINGPARSER_21_034: [**If the hostNameString is NULL, connectionstringparser_splitHostName shall return __FAILURE__.**]**
**SRS_CONNECTIONSTRINGPARSER_21_033: [** connectionstringparser_splitHostName shall convert the hostNameString to a connection_string passed in as argument, and call connectionstringparser_splitHostName_from_char. **]**
**SRS_CONNECTIONSTRINGPARSER_21_034: [** If the hostNameString is NULL, connectionstringparser_splitHostName shall return __FAILURE__. **]**

56
devdoc/constbuffer_requirements.md
Просмотреть файл

@ -39,47 +39,59 @@ extern const CONSTBUFFER* CONSTBUFFER_GetContent(CONSTBUFFER_HANDLE constbufferH
extern void CONSTBUFFER_HANDLE_Destroy(CONSTBUFFER constbufferHandle);
```
### ConstBuffer_Create
### ConstBuffer_Create
```C
extern CONSTBUFFER_HANDLE CONSTBUFFER_Create(const unsigned char* source, size_t size);
```
**SRS_CONSTBUFFER_02_001: [**If `source` is NULL and `size` is different than 0 then CONSTBUFFER_Create shall fail and return NULL.**]**
**SRS_CONSTBUFFER_02_002: [**Otherwise, `CONSTBUFFER_Create` shall create a copy of the memory area pointed to by `source` having `size` bytes.**]**
**SRS_CONSTBUFFER_02_003: [**If creating the copy fails then `CONSTBUFFER_Create` shall return NULL.**]**
**SRS_CONSTBUFFER_02_004: [**Otherwise `CONSTBUFFER_Create` shall return a non-NULL handle.**]**
**SRS_CONSTBUFFER_02_005: [**The non-NULL handle returned by `CONSTBUFFER_Create` shall have its ref count set to "1".**]**
**SRS_CONSTBUFFER_02_001: [** If `source` is NULL and `size` is different than 0 then CONSTBUFFER_Create shall fail and return NULL. **]**
###CONSTBUFFER_CreateFromBuffer
**SRS_CONSTBUFFER_02_002: [** Otherwise, `CONSTBUFFER_Create` shall create a copy of the memory area pointed to by `source` having `size` bytes. **]**
**SRS_CONSTBUFFER_02_003: [** If creating the copy fails then `CONSTBUFFER_Create` shall return NULL. **]**
**SRS_CONSTBUFFER_02_004: [** Otherwise `CONSTBUFFER_Create` shall return a non-NULL handle. **]**
**SRS_CONSTBUFFER_02_005: [** The non-NULL handle returned by `CONSTBUFFER_Create` shall have its ref count set to "1". **]**
### CONSTBUFFER_CreateFromBuffer
```C
extern CONSTBUFFER_HANDLE CONSTBUFFER_CreateFromBuffer(BUFFER_HANDLE buffer);
```
**SRS_CONSTBUFFER_02_006: [**If `buffer` is NULL then `CONSTBUFFER_CreateFromBuffer` shall fail and return NULL.**]**
**SRS_CONSTBUFFER_02_007: [**Otherwise, `CONSTBUFFER_CreateFromBuffer` shall copy the content of `buffer`.**]**
**SRS_CONSTBUFFER_02_008: [**If copying the content fails, then `CONSTBUFFER_CreateFromBuffer` shall fail and return NULL.**]**
**SRS_CONSTBUFFER_02_009: [**Otherwise, `CONSTBUFFER_CreateFromBuffer` shall return a non-NULL handle.**]**
**SRS_CONSTBUFFER_02_010: [**The non-NULL handle returned by `CONSTBUFFER_CreateFromBuffer` shall have its ref count set to "1".**]**
**SRS_CONSTBUFFER_02_006: [** If `buffer` is NULL then `CONSTBUFFER_CreateFromBuffer` shall fail and return NULL. **]**
###CONSTBUFFER_GetContent
**SRS_CONSTBUFFER_02_007: [** Otherwise, `CONSTBUFFER_CreateFromBuffer` shall copy the content of `buffer`. **]**
**SRS_CONSTBUFFER_02_008: [** If copying the content fails, then `CONSTBUFFER_CreateFromBuffer` shall fail and return NULL. **]**
**SRS_CONSTBUFFER_02_009: [** Otherwise, `CONSTBUFFER_CreateFromBuffer` shall return a non-NULL handle. **]**
**SRS_CONSTBUFFER_02_010: [** The non-NULL handle returned by `CONSTBUFFER_CreateFromBuffer` shall have its ref count set to "1". **]**
### CONSTBUFFER_GetContent
```C
extern const CONSTBUFFER* CONSTBUFFER_GetContent(CONSTBUFFER_HANDLE constbufferHandle);
```
**SRS_CONSTBUFFER_02_011: [**If `constbufferHandle` is NULL then CONSTBUFFER_GetContent shall return NULL.**]**
**SRS_CONSTBUFFER_02_012: [**Otherwise, `CONSTBUFFER_GetContent` shall return a `const CONSTBUFFER*` that matches byte by byte the original bytes used to created the const buffer and has the same length.**]**
**SRS_CONSTBUFFER_02_011: [** If `constbufferHandle` is NULL then CONSTBUFFER_GetContent shall return NULL. **]**
###CONSTBUFFER_Clone
**SRS_CONSTBUFFER_02_012: [** Otherwise, `CONSTBUFFER_GetContent` shall return a `const CONSTBUFFER*` that matches byte by byte the original bytes used to created the const buffer and has the same length. **]**
### CONSTBUFFER_Clone
```C
extern CONSTBUFFER_HANDLE CONSTBUFFER_Clone(CONSTBUFFER_HANDLE constbufferHandle);
```
**SRS_CONSTBUFFER_02_013: [**If `constbufferHandle` is NULL then CONSTBUFFER_Clone shall fail and return NULL.**]**
**SRS_CONSTBUFFER_02_014: [**Otherwise, `CONSTBUFFER_Clone` shall increment the reference count and return `constbufferHandle`.**]**
**SRS_CONSTBUFFER_02_013: [** If `constbufferHandle` is NULL then CONSTBUFFER_Clone shall fail and return NULL. **]**
###CONSTBUFFER_Destroy
**SRS_CONSTBUFFER_02_014: [** Otherwise, `CONSTBUFFER_Clone` shall increment the reference count and return `constbufferHandle`. **]**
### CONSTBUFFER_Destroy
```C
extern void CONSTBUFFER_Destroy(CONSTBUFFER_HANDLE constbufferHandle);
```
**SRS_CONSTBUFFER_02_015: [**If `constbufferHandle` is NULL then `CONSTBUFFER_Destroy` shall do nothing.**]**
**SRS_CONSTBUFFER_02_016: [**Otherwise, `CONSTBUFFER_Destroy` shall decrement the refcount on the `constbufferHandle` handle.**]**
**SRS_CONSTBUFFER_02_017: [**If the refcount reaches zero, then `CONSTBUFFER_Destroy` shall deallocate all resources used by the CONSTBUFFER_HANDLE.**]**
**SRS_CONSTBUFFER_02_015: [** If `constbufferHandle` is NULL then `CONSTBUFFER_Destroy` shall do nothing. **]**
**SRS_CONSTBUFFER_02_016: [** Otherwise, `CONSTBUFFER_Destroy` shall decrement the refcount on the `constbufferHandle` handle. **]**
**SRS_CONSTBUFFER_02_017: [** If the refcount reaches zero, then `CONSTBUFFER_Destroy` shall deallocate all resources used by the CONSTBUFFER_HANDLE. **]**

89
devdoc/constmap_requirements.md
Просмотреть файл

@ -37,81 +37,100 @@ extern CONSTMAP_RESULT ConstMap_GetInternals(CONSTMAP_HANDLE handle, const char*
```
### ConstMap_Create
### ConstMap_Create
```C
extern CONSTMAP_HANDLE ConstMap_Create(MAP_HANDLE sourceMap);
```
**SRS_CONSTMAP_17_001: [**`ConstMap_Create` shall create an immutable map, populated by the key, value pairs in the source map.**]**
**SRS_CONSTMAP_17_048: [**`ConstMap_Create` shall accept any non-`NULL` `MAP_HANDLE` as input.**]**
**SRS_CONSTMAP_17_002: [**If during creation there are any errors, then `ConstMap_Create` shall return `NULL`.**]**
**SRS_CONSTMAP_17_003: [**Otherwise, it shall return a non-`NULL` handle that can be used in subsequent calls.**]**
**SRS_CONSTMAP_17_001: [** `ConstMap_Create` shall create an immutable map, populated by the key, value pairs in the source map. **]**
### ConstMap_Destroy
**SRS_CONSTMAP_17_048: [** `ConstMap_Create` shall accept any non-`NULL` `MAP_HANDLE` as input. **]**
**SRS_CONSTMAP_17_002: [** If during creation there are any errors, then `ConstMap_Create` shall return `NULL`. **]**
**SRS_CONSTMAP_17_003: [** Otherwise, it shall return a non-`NULL` handle that can be used in subsequent calls. **]**
### ConstMap_Destroy
```C
extern void ConstMap_Destroy(CONSTMAP_HANDLE handle);
```
**SRS_CONSTMAP_17_005: [**If parameter handle is `NULL` then `ConstMap_Destroy` shall take no action.**]**
**SRS_CONSTMAP_17_049: [**`ConstMap_Destroy` shall decrement the internal reference count of the immutable map.**]**
**SRS_CONSTMAP_17_004: [**If the reference count is zero, `ConstMap_Destroy` shall release all resources associated with the immutable map.**]**
**SRS_CONSTMAP_17_005: [** If parameter handle is `NULL` then `ConstMap_Destroy` shall take no action. **]**
**SRS_CONSTMAP_17_049: [** `ConstMap_Destroy` shall decrement the internal reference count of the immutable map. **]**
**SRS_CONSTMAP_17_004: [** If the reference count is zero, `ConstMap_Destroy` shall release all resources associated with the immutable map. **]**
### ConstMap_Clone
### ConstMap_Clone
```C
extern CONSTMAP_HANDLE ConstMap_Clone(CONSTMAP_HANDLE handle);
```
**SRS_CONSTMAP_17_038: [**`ConstMap_Clone` returns `NULL` if parameter `handle` is `NULL`.**]**
**SRS_CONSTMAP_17_039: [**`ConstMap_Clone` shall increase the internal reference count of the immutable map indicated by parameter `handle`**]**
**SRS_CONSTMAP_17_050: [**`ConstMap_Clone` shall return the non-`NULL` handle. **]**
**SRS_CONSTMAP_17_038: [** `ConstMap_Clone` returns `NULL` if parameter `handle` is `NULL`. **]**
### ConstMap_CloneWriteable
**SRS_CONSTMAP_17_039: [** `ConstMap_Clone` shall increase the internal reference count of the immutable map indicated by parameter `handle` **]**
**SRS_CONSTMAP_17_050: [** `ConstMap_Clone` shall return the non-`NULL` handle. **]**
### ConstMap_CloneWriteable
```C
extern MAP_HANDLE ConstMap_CloneWriteable(CONSTMAP_HANDLE handle);
```
This function will return a new MAP_HANDLE populated by the key, value pairs contained in the CONSTMAP_HANDLE. This MAP_HANDLE needs to be destroyed when it is no longer needed.
**SRS_CONSTMAP_17_051: [**`ConstMap_CloneWriteable` returns `NULL` if parameter handle is `NULL`. **]**
**SRS_CONSTMAP_17_052: [**`ConstMap_CloneWriteable` shall create a new, writeable map, populated by the key, value pairs in the parameter defined by `handle`.**]**
**SRS_CONSTMAP_17_053: [**If during copying, any operation fails, then `ConstMap_CloneWriteableap_Clone` shall return `NULL`.**]**
**SRS_CONSTMAP_17_054: [**Otherwise, `ConstMap_CloneWriteable` shall return a non-`NULL` handle that can be used in subsequent calls.**]**
**SRS_CONSTMAP_17_051: [** `ConstMap_CloneWriteable` returns `NULL` if parameter handle is `NULL`. **]**
**SRS_CONSTMAP_17_052: [** `ConstMap_CloneWriteable` shall create a new, writeable map, populated by the key, value pairs in the parameter defined by `handle`. **]**
**SRS_CONSTMAP_17_053: [** If during copying, any operation fails, then `ConstMap_CloneWriteableap_Clone` shall return `NULL`. **]**
**SRS_CONSTMAP_17_054: [** Otherwise, `ConstMap_CloneWriteable` shall return a non-`NULL` handle that can be used in subsequent calls. **]**
### ConstMap_ContainsKey
### ConstMap_ContainsKey
```C
extern bool ConstMap_ContainsKey(CONSTMAP_HANDLE handle, const char* key);
```
`ConstMap_ContainsKey` returns `true` if the map contains a key with the same value as parameter `key`.
**SRS_CONSTMAP_17_024: [**If parameter `handle` or `key` are `NULL` then `ConstMap_ContainsKey` shall return `false`.**]**
**SRS_CONSTMAP_17_025: [**Otherwise if a key exists then `ConstMap_ContainsKey` shall return `true`.**]**
**SRS_CONSTMAP_17_026: [**If a key doesn't exist, then `ConstMap_ContainsKey` shall return `false`.**]**
**SRS_CONSTMAP_17_024: [** If parameter `handle` or `key` are `NULL` then `ConstMap_ContainsKey` shall return `false`. **]**
### ConstMap_ContainsValue
**SRS_CONSTMAP_17_025: [** Otherwise if a key exists then `ConstMap_ContainsKey` shall return `true`. **]**
**SRS_CONSTMAP_17_026: [** If a key doesn't exist, then `ConstMap_ContainsKey` shall return `false`. **]**
### ConstMap_ContainsValue
```C
extern bool ConstMap_ContainsValue(CONSTMAP_HANDLE handle, const char* value);
```
`ConstMap_ContainsKey` returns `true` if at least one pair <key,value> in the map contains the `value` parameter.
**SRS_CONSTMAP_17_027: [**If parameter `handle` or `value` is `NULL` then `ConstMap_ContainsValue` shall return `false`.**]**
**SRS_CONSTMAP_17_028: [**Otherwise, if a pair <key, value> has its value equal to the parameter `value`, the `ConstMap_ContainsValue` shall return `true`.**]**
**SRS_CONSTMAP_17_029: [**Otherwise, if such a <key, value> does not exist, then `ConstMap_ContainsValue` shall return `false`.**]**
**SRS_CONSTMAP_17_027: [** If parameter `handle` or `value` is `NULL` then `ConstMap_ContainsValue` shall return `false`. **]**
### ConstMap_GetValue
**SRS_CONSTMAP_17_028: [** Otherwise, if a pair <key, value> has its value equal to the parameter `value`, the `ConstMap_ContainsValue` shall return `true`. **]**
**SRS_CONSTMAP_17_029: [** Otherwise, if such a <key, value> does not exist, then `ConstMap_ContainsValue` shall return `false`. **]**
### ConstMap_GetValue
```C
extern const char* ConstMap_GetValue(CONSTMAP_HANDLE handle, const char* key);
```
`ConstMap_GetValue` returns the value of a stored key.
**SRS_CONSTMAP_17_040: [**If parameter `handle` or `key` is `NULL` then `ConstMap_GetValue` returns `NULL`.**]**
**SRS_CONSTMAP_17_041: [**If the key is not found, then `ConstMap_GetValue` returns `NULL`.**]**
**SRS_CONSTMAP_17_042: [**Otherwise, `ConstMap_GetValue` returns the key's value.**]**
**SRS_CONSTMAP_17_040: [** If parameter `handle` or `key` is `NULL` then `ConstMap_GetValue` returns `NULL`. **]**
### ConstMap_GetInternals
**SRS_CONSTMAP_17_041: [** If the key is not found, then `ConstMap_GetValue` returns `NULL`. **]**
**SRS_CONSTMAP_17_042: [** Otherwise, `ConstMap_GetValue` returns the key's value. **]**
### ConstMap_GetInternals
```C
extern CONSTMAP_RESULT ConstMap_GetInternals(CONSTMAP_HANDLE handle, const char*const** keys, const char*const** values, size_t* count);
```
**SRS_CONSTMAP_17_046: [**If parameter `handle`, `keys`, `values` or `count` is `NULL` then `ConstMap_GetInternals` shall return `CONSTMAP_INVALIDARG`.**]**
**SRS_CONSTMAP_17_043: [**`ConstMap_GetInternals` shall produce in `*keys` a pointer to an array of `const char*` having all the keys stored so far by the map.**]**
**SRS_CONSTMAP_17_044: [**`ConstMap_GetInternals` shall produce in `*values` a pointer to an array of `const char*` having all the values stored so far by the map.**]**
**SRS_CONSTMAP_17_045: [** `ConstMap_GetInternals` shall produce in `*count` the number of stored keys and values.**]**
**SRS_CONSTMAP_17_046: [** If parameter `handle`, `keys`, `values` or `count` is `NULL` then `ConstMap_GetInternals` shall return `CONSTMAP_INVALIDARG`. **]**
**SRS_CONSTMAP_17_043: [** `ConstMap_GetInternals` shall produce in `*keys` a pointer to an array of `const char*` having all the keys stored so far by the map. **]**
**SRS_CONSTMAP_17_044: [** `ConstMap_GetInternals` shall produce in `*values` a pointer to an array of `const char*` having all the values stored so far by the map. **]**
**SRS_CONSTMAP_17_045: [** `ConstMap_GetInternals` shall produce in `*count` the number of stored keys and values. **]**

245
devdoc/crt_abstraction_requirements.md
Просмотреть файл

@ -1,15 +1,16 @@
CRTAbstractions Requirements
================
##Overview
## Overview
Many old CRT functions have newer, more secure versions via Microsoft's implementation of the run-time library. These have the _s ("secure") suffix.
The CRTAbstractions module provides the same secure functions for when not using a Microsoft platforms.
##Generic Requirements
## Generic Requirements
**SRS_CRT_ABSTRACTIONS_99_001: [**The module shall not redefine the secure functions implemented by Microsoft CRT.**]**
**SRS_CRT_ABSTRACTIONS_99_040: [**The module shall still compile when building on a Microsoft platform.**]**
**SRS_CRT_ABSTRACTIONS_99_001: [** The module shall not redefine the secure functions implemented by Microsoft CRT. **]**
**SRS_CRT_ABSTRACTIONS_99_040: [** The module shall still compile when building on a Microsoft platform. **]**
##Exposed API
**SRS_CRT_ABSTRACTIONS_99_002: [**
@ -23,149 +24,209 @@ int mallocAndStrcpy_s(char** destination, const char* source);
int unsignedIntToString(char* destination, size_t destinationSize, unsigned int value);
int size_tToString(char* destination, size_t destinationSize, size_t value);
```
**]**
**]**
###strcat_s
### strcat_s
```c
int strcat_s(char* dst, size_t dstSizeInBytes, const char* src);
```
**SRS_CRT_ABSTRACTIONS_99_008: [**strcat_s shall append the src to dst and terminates the resulting string with a null character.**]**
**SRS_CRT_ABSTRACTIONS_99_009: [**The initial character of src shall overwrite the terminating null character of dst.**]**
**SRS_CRT_ABSTRACTIONS_99_003: [**strcat_s shall return Zero upon success.**]**
**SRS_CRT_ABSTRACTIONS_99_008: [** strcat_s shall append the src to dst and terminates the resulting string with a null character. **]**
**SRS_CRT_ABSTRACTIONS_99_009: [** The initial character of src shall overwrite the terminating null character of dst. **]**
**SRS_CRT_ABSTRACTIONS_99_003: [** strcat_s shall return Zero upon success. **]**
strcat_s shall return an error code upon failure as follows:
**SRS_CRT_ABSTRACTIONS_99_004: [**If dst is NULL or unterminated, the error code returned shall be EINVAL & dst shall not be modified.**]**
**SRS_CRT_ABSTRACTIONS_99_005: [**If src is NULL, the error code returned shall be EINVAL and dst[0**]** shall be set to 0.]
**SRS_CRT_ABSTRACTIONS_99_006: [**If the dstSizeInBytes is 0 or smaller than the required size for dst & src, the error code returned shall be ERANGE & dst[0**]** set to 0.]
**SRS_CRT_ABSTRACTIONS_99_004: [** If dst is NULL or unterminated, the error code returned shall be EINVAL & dst shall not be modified. **]**
###strcpy_s
**SRS_CRT_ABSTRACTIONS_99_005: [** If src is NULL, the error code returned shall be EINVAL and dst[0 **]** shall be set to 0.]
**SRS_CRT_ABSTRACTIONS_99_006: [** If the dstSizeInBytes is 0 or smaller than the required size for dst & src, the error code returned shall be ERANGE & dst[0 **]** set to 0.]
### strcpy_s
```c
int strcpy_s(char* dst, size_t dstSizeInBytes, const char* src);
```
**SRS_CRT_ABSTRACTIONS_99_016: [**strcpy_s shall copy the contents in the address of src, including the terminating null character, to the location that's specified by dst.**]**
**SRS_CRT_ABSTRACTIONS_99_011: [**strcpy_s shall return Zero upon success**]**
**SRS_CRT_ABSTRACTIONS_99_016: [** strcpy_s shall copy the contents in the address of src, including the terminating null character, to the location that's specified by dst. **]**
**SRS_CRT_ABSTRACTIONS_99_011: [** strcpy_s shall return Zero upon success **]**
strcpy shall return an error code upon failure as follows:
**SRS_CRT_ABSTRACTIONS_99_012: [**If dst is NULL, the error code returned shall be EINVAL & dst shall not be modified.**]**
**SRS_CRT_ABSTRACTIONS_99_013: [**If src is NULL, the error code returned shall be EINVAL and dst[0**]** shall be set to 0.]
**SRS_CRT_ABSTRACTIONS_99_014: [**If the dstSizeInBytes is 0 or smaller than the required size for the src string, the error code returned shall be ERANGE & dst[0**]** set to 0.]
**SRS_CRT_ABSTRACTIONS_99_012: [** If dst is NULL, the error code returned shall be EINVAL & dst shall not be modified. **]**
###strncpy_s
**SRS_CRT_ABSTRACTIONS_99_013: [** If src is NULL, the error code returned shall be EINVAL and dst[0 **]** shall be set to 0.]
**SRS_CRT_ABSTRACTIONS_99_014: [** If the dstSizeInBytes is 0 or smaller than the required size for the src string, the error code returned shall be ERANGE & dst[0 **]** set to 0.]
### strncpy_s
```c
int strncpy_s(char* dst, size_t dstSizeInBytes, const char* src, size_t maxCount);
```
**SRS_CRT_ABSTRACTIONS_99_025: [**strncpy_s shall copy the first N characters of src to dst, where N is the lesser of MaxCount and the length of src.**]**
**SRS_CRT_ABSTRACTIONS_99_041: [**If those N characters will fit within dst (whose size is given as dstSizeInBytes) and still leave room for a null terminator, then those characters shall be copied and a terminating null is appended; otherwise, strDest[0**]** is set to the null character and ERANGE error code returned.]
**SRS_CRT_ABSTRACTIONS_99_026: [**If MaxCount is _TRUNCATE (defined as -1), then as much of src as will fit into dst shall be copied while still leaving room for the terminating null to be appended.**]**
**SRS_CRT_ABSTRACTIONS_99_018: [**strncpy_s shall return Zero upon success**]**
**SRS_CRT_ABSTRACTIONS_99_025: [** strncpy_s shall copy the first N characters of src to dst, where N is the lesser of MaxCount and the length of src. **]**
**SRS_CRT_ABSTRACTIONS_99_041: [** If those N characters will fit within dst (whose size is given as dstSizeInBytes) and still leave room for a null terminator, then those characters shall be copied and a terminating null is appended; otherwise, strDest[0 **]** is set to the null character and ERANGE error code returned.]
**SRS_CRT_ABSTRACTIONS_99_026: [** If MaxCount is _TRUNCATE (defined as -1), then as much of src as will fit into dst shall be copied while still leaving room for the terminating null to be appended. **]**
**SRS_CRT_ABSTRACTIONS_99_018: [** strncpy_s shall return Zero upon success **]**
strncpy_s shall return an error code upon failure as follows:
**SRS_CRT_ABSTRACTIONS_99_019: [**If truncation occurred as a result of the copy, the error code returned shall be STRUNCATE.**]**
**SRS_CRT_ABSTRACTIONS_99_020: [**If dst is NULL, the error code returned shall be EINVAL and dst shall not be modified.**]**
**SRS_CRT_ABSTRACTIONS_99_021: [**If src is NULL, the error code returned shall be EINVAL and dst[0**]** shall be set to 0.]
**SRS_CRT_ABSTRACTIONS_99_022: [**If the dstSizeInBytes is 0, the error code returned shall be EINVAL and dst shall not be modified.**]**
**SRS_CRT_ABSTRACTIONS_99_023: [**If dst is not NULL & dstSizeInBytes is smaller than the required size for the src string, the error code returned shall be ERANGE and dst[0**]** shall be set to 0.]
**SRS_CRT_ABSTRACTIONS_99_019: [** If truncation occurred as a result of the copy, the error code returned shall be STRUNCATE. **]**
###sprintf_s
**SRS_CRT_ABSTRACTIONS_99_020: [** If dst is NULL, the error code returned shall be EINVAL and dst shall not be modified. **]**
**SRS_CRT_ABSTRACTIONS_99_021: [** If src is NULL, the error code returned shall be EINVAL and dst[0 **]** shall be set to 0.]
**SRS_CRT_ABSTRACTIONS_99_022: [** If the dstSizeInBytes is 0, the error code returned shall be EINVAL and dst shall not be modified. **]**
**SRS_CRT_ABSTRACTIONS_99_023: [** If dst is not NULL & dstSizeInBytes is smaller than the required size for the src string, the error code returned shall be ERANGE and dst[0 **]** shall be set to 0.]
### sprintf_s
```c
int sprintf_s(char* dst, size_t dstSizeInBytes, const char* format, ... );
```
**SRS_CRT_ABSTRACTIONS_99_029: [**The sprintf_s function shall format and store series of characters and values in dst. Each argument (if any) is converted and output according to the corresponding Format Specification in the format variable.**]**
**SRS_CRT_ABSTRACTIONS_99_031: [**A null character is appended after the last character written.**]**
**SRS_CRT_ABSTRACTIONS_99_027: [**sprintf_s shall return the number of characters stored in dst upon success. This number shall not include the terminating null character.**]**
**SRS_CRT_ABSTRACTIONS_99_028: [**If dst or format is a null pointer, sprintf_s shall return -1 and set errno to EINVAL**]**
**SRS_CRT_ABSTRACTIONS_99_034: [**If the dst buffer is too small for the text being printed, then dst is set to an empty string and the function shall return -1.**]**
**SRS_CRT_ABSTRACTIONS_99_029: [** The sprintf_s function shall format and store series of characters and values in dst. Each argument (if any) is converted and output according to the corresponding Format Specification in the format variable. **]**
###mallocAndStrcpy_s
**SRS_CRT_ABSTRACTIONS_99_031: [** A null character is appended after the last character written. **]**
**SRS_CRT_ABSTRACTIONS_99_027: [** sprintf_s shall return the number of characters stored in dst upon success. This number shall not include the terminating null character. **]**
**SRS_CRT_ABSTRACTIONS_99_028: [** If dst or format is a null pointer, sprintf_s shall return -1 and set errno to EINVAL **]**
**SRS_CRT_ABSTRACTIONS_99_034: [** If the dst buffer is too small for the text being printed, then dst is set to an empty string and the function shall return -1. **]**
### mallocAndStrcpy_s
```c
int mallocAndStrcpy_s(char** destination, const char* source);
```
**SRS_CRT_ABSTRACTIONS_99_038: [**mallocAndstrcpy_s shall allocate memory for destination buffer to fit the string in the source parameter.**]**
**SRS_CRT_ABSTRACTIONS_99_039: [**mallocAndstrcpy_s shall copy the contents in the address source, including the terminating null character into location specified by the destination pointer after the memory allocation.**]**
**SRS_CRT_ABSTRACTIONS_99_035: [**mallocAndstrcpy_s shall return Zero upon success**]**
**SRS_CRT_ABSTRACTIONS_99_038: [** mallocAndstrcpy_s shall allocate memory for destination buffer to fit the string in the source parameter. **]**
**SRS_CRT_ABSTRACTIONS_99_039: [** mallocAndstrcpy_s shall copy the contents in the address source, including the terminating null character into location specified by the destination pointer after the memory allocation. **]**
**SRS_CRT_ABSTRACTIONS_99_035: [** mallocAndstrcpy_s shall return Zero upon success **]**
mallocAndstrcpy_s shall return an error code upon failure as follows:
**SRS_CRT_ABSTRACTIONS_99_036: [**destination parameter or source parameter is NULL, the error code returned shall be EINVAL and destination shall not be modified.**]**
**SRS_CRT_ABSTRACTIONS_99_037: [**Upon failure to allocate memory for the destination, the function will return ENOMEM.**]**
**SRS_CRT_ABSTRACTIONS_99_036: [** destination parameter or source parameter is NULL, the error code returned shall be EINVAL and destination shall not be modified. **]**
###unsignedIntToString
**SRS_CRT_ABSTRACTIONS_99_037: [** Upon failure to allocate memory for the destination, the function will return ENOMEM. **]**
### unsignedIntToString
```c
int unsignedIntToString(char* destination, size_t destinationSize, unsigned int value)
```
**SRS_CRT_ABSTRACTIONS_02_001: [**unsignedIntToString shall convert the parameter value to its decimal representation as a string in the buffer indicated by parameter destination having the size indicated by parameter destinationSize.**]**
**SRS_CRT_ABSTRACTIONS_02_002: [**If the conversion fails for any reason (for example, insufficient buffer space), a non-zero return value shall be supplied and unsignedIntToString shall fail.**]**
**SRS_CRT_ABSTRACTIONS_02_003: [**If destination is NULL then unsignedIntToString shall fail.**]**
**SRS_CRT_ABSTRACTIONS_02_004: [**If the conversion has been successfull then unsignedIntToString shall return 0.**]**
**SRS_CRT_ABSTRACTIONS_02_001: [** unsignedIntToString shall convert the parameter value to its decimal representation as a string in the buffer indicated by parameter destination having the size indicated by parameter destinationSize. **]**
###size_tToString
**SRS_CRT_ABSTRACTIONS_02_002: [** If the conversion fails for any reason (for example, insufficient buffer space), a non-zero return value shall be supplied and unsignedIntToString shall fail. **]**
**SRS_CRT_ABSTRACTIONS_02_003: [** If destination is NULL then unsignedIntToString shall fail. **]**
**SRS_CRT_ABSTRACTIONS_02_004: [** If the conversion has been successfull then unsignedIntToString shall return 0. **]**
### size_tToString
```c
int size_tToString(char* destination, size_t destinationSize, size_t value)
```
**SRS_CRT_ABSTRACTIONS_02_001: [**size_tToString shall convert the parameter value to its decimal representation as a string in the buffer indicated by parameter destination having the size indicated by parameter destinationSize.**]**
**SRS_CRT_ABSTRACTIONS_02_002: [**If the conversion fails for any reason (for example, insufficient buffer space), a non-zero return value shall be supplied and size_tToString shall fail.**]**
**SRS_CRT_ABSTRACTIONS_02_003: [**If destination is NULL then size_tToString shall fail.**]**
**SRS_CRT_ABSTRACTIONS_02_004: [**If the conversion has been successfull then size_tToString shall return 0.**]**
**SRS_CRT_ABSTRACTIONS_02_001: [** size_tToString shall convert the parameter value to its decimal representation as a string in the buffer indicated by parameter destination having the size indicated by parameter destinationSize. **]**
###strtoull_s
**SRS_CRT_ABSTRACTIONS_02_002: [** If the conversion fails for any reason (for example, insufficient buffer space), a non-zero return value shall be supplied and size_tToString shall fail. **]**
**SRS_CRT_ABSTRACTIONS_02_003: [** If destination is NULL then size_tToString shall fail. **]**
**SRS_CRT_ABSTRACTIONS_02_004: [** If the conversion has been successfull then size_tToString shall return 0. **]**
### strtoull_s
```c
unsigned long long strtoull_s(const char* nptr, char** endptr, int base)
```
**SRS_CRT_ABSTRACTIONS_21_001: [**The strtoull_s must convert the initial portion of the string pointed to by nptr to unsigned long long int representation.**]**
**SRS_CRT_ABSTRACTIONS_21_002: [**The strtoull_s must resembling an integer represented in some radix determined by the value of base.**]**
**SRS_CRT_ABSTRACTIONS_21_003: [**The strtoull_s must return the integer that represents the value in the initial part of the string. If any.**]**
**SRS_CRT_ABSTRACTIONS_21_004: [**The strtoull_s must return in endptr a final string of one or more unrecognized characters, including the terminating null character of the input string.**]**
**SRS_CRT_ABSTRACTIONS_21_005: [**The strtoull_s must convert number using base 2 to 36.**]**
**SRS_CRT_ABSTRACTIONS_21_006: [**The strtoull_s must use the letters from a (or A) through z (or Z) to represent the numbers between 10 to 35.**]**
**SRS_CRT_ABSTRACTIONS_21_007: [**If the base is 0 and no special chars precedes the number, strtoull_s must convert to a decimal (base 10).**]**
**SRS_CRT_ABSTRACTIONS_21_008: [**If the base is 0 and '0x' or '0X' precedes the number, strtoull_s must convert to a hexadecimal (base 16).**]**
**SRS_CRT_ABSTRACTIONS_21_009: [**If the base is 0 and '0' precedes the number, strtoull_s must convert to an octal (base 8).**]**
**SRS_CRT_ABSTRACTIONS_21_010: [**The white-space must be one of the characters ' ', '\f', '\n', '\r', '\t', '\v'.**]**
**SRS_CRT_ABSTRACTIONS_21_011: [**The valid sequence starts after the first non-white-space character, followed by an optional positive or negative sign, a number or a letter (depending of the base).**]**
**SRS_CRT_ABSTRACTIONS_21_012: [**If the subject sequence is empty or does not have the expected form, the strtoull_s must **not** perform any conversion and must returns 0L; the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a NULL pointer.**]**
**SRS_CRT_ABSTRACTIONS_21_013: [**If no conversion could be performed, the strtoull_s returns the value 0L.**]**
**SRS_CRT_ABSTRACTIONS_21_014: [**If the correct value is outside the range, the strtoull_s returns the value ULLONG_MAX, and errno will receive the value ERANGE.**]**
**SRS_CRT_ABSTRACTIONS_21_035: [**If the nptr is NULL, the strtoull_s must **not** perform any conversion and must returns 0L; endptr must receive NULL, provided that endptr is not a NULL pointer.**]**
**SRS_CRT_ABSTRACTIONS_21_038: [**If the subject sequence starts with a negative sign, the strtoull_s will convert it to the posive representation of the negative value.**]**
**SRS_CRT_ABSTRACTIONS_21_001: [** The strtoull_s must convert the initial portion of the string pointed to by nptr to unsigned long long int representation. **]**
###strtof_s
**SRS_CRT_ABSTRACTIONS_21_002: [** The strtoull_s must resembling an integer represented in some radix determined by the value of base. **]**
**SRS_CRT_ABSTRACTIONS_21_003: [** The strtoull_s must return the integer that represents the value in the initial part of the string. If any. **]**
**SRS_CRT_ABSTRACTIONS_21_004: [** The strtoull_s must return in endptr a final string of one or more unrecognized characters, including the terminating null character of the input string. **]**
**SRS_CRT_ABSTRACTIONS_21_005: [** The strtoull_s must convert number using base 2 to 36. **]**
**SRS_CRT_ABSTRACTIONS_21_006: [** The strtoull_s must use the letters from a (or A) through z (or Z) to represent the numbers between 10 to 35. **]**
**SRS_CRT_ABSTRACTIONS_21_007: [** If the base is 0 and no special chars precedes the number, strtoull_s must convert to a decimal (base 10). **]**
**SRS_CRT_ABSTRACTIONS_21_008: [** If the base is 0 and '0x' or '0X' precedes the number, strtoull_s must convert to a hexadecimal (base 16). **]**
**SRS_CRT_ABSTRACTIONS_21_009: [** If the base is 0 and '0' precedes the number, strtoull_s must convert to an octal (base 8). **]**
**SRS_CRT_ABSTRACTIONS_21_010: [** The white-space must be one of the characters ' ', '\f', '\n', '\r', '\t', '\v'. **]**
**SRS_CRT_ABSTRACTIONS_21_011: [** The valid sequence starts after the first non-white-space character, followed by an optional positive or negative sign, a number or a letter (depending of the base). **]**
**SRS_CRT_ABSTRACTIONS_21_012: [** If the subject sequence is empty or does not have the expected form, the strtoull_s must **not** perform any conversion and must returns 0L; the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a NULL pointer. **]**
**SRS_CRT_ABSTRACTIONS_21_013: [** If no conversion could be performed, the strtoull_s returns the value 0L. **]**
**SRS_CRT_ABSTRACTIONS_21_014: [** If the correct value is outside the range, the strtoull_s returns the value ULLONG_MAX, and errno will receive the value ERANGE. **]**
**SRS_CRT_ABSTRACTIONS_21_035: [** If the nptr is NULL, the strtoull_s must **not** perform any conversion and must returns 0L; endptr must receive NULL, provided that endptr is not a NULL pointer. **]**
**SRS_CRT_ABSTRACTIONS_21_038: [** If the subject sequence starts with a negative sign, the strtoull_s will convert it to the posive representation of the negative value. **]**
### strtof_s
```c
float strtof_s(const char* nptr, char** endptr)
```
**SRS_CRT_ABSTRACTIONS_21_015: [**The strtof_s must convert the initial portion of the string pointed to by nptr to float representation.**]**
**SRS_CRT_ABSTRACTIONS_21_016: [**The strtof_s must return the float that represents the value in the initial part of the string. If any.**]**
**SRS_CRT_ABSTRACTIONS_21_017: [**The strtof_s must return in endptr a final string of one or more unrecognized characters, including the terminating null character of the input string.**]**
**SRS_CRT_ABSTRACTIONS_21_018: [**The white-space for strtof_s must be one of the characters ' ', '\f', '\n', '\r', '\t', '\v'.**]**
**SRS_CRT_ABSTRACTIONS_21_019: [**The valid sequence for strtof_s starts after the first non-white-space character, followed by an optional positive or negative sign, a number, 'INF', or 'NAN' (ignoring case).**]**
**SRS_CRT_ABSTRACTIONS_21_020: [**If the subject sequence is empty or does not have the expected form, the strtof_s must **not** perform any conversion and must returns 0.0f; the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a NULL pointer.**]**
**SRS_CRT_ABSTRACTIONS_21_021: [**If no conversion could be performed, the strtof_s returns the value 0.0f.**]**
**SRS_CRT_ABSTRACTIONS_21_022: [**If the correct value is outside the range, the strtof_s returns the value plus or minus HUGE_VALF, and errno will receive the value ERANGE.**]**
**SRS_CRT_ABSTRACTIONS_21_023: [**If the string is 'INF' of 'INFINITY' (ignoring case), the strtof_s must return the INFINITY value for float.**]**
**SRS_CRT_ABSTRACTIONS_21_024: [**If the string is 'NAN' or 'NAN(...)' (ignoring case), the strtof_s must return 0.0f and points endptr to the first character after the 'NAN' sequence.**]**
**SRS_CRT_ABSTRACTIONS_21_036: [**If the nptr is NULL, the strtof_s must **not** perform any conversion and must returns 0.0f; endptr must receive NULL, provided that endptr is not a NULL pointer.**]**
**SRS_CRT_ABSTRACTIONS_21_015: [** The strtof_s must convert the initial portion of the string pointed to by nptr to float representation. **]**
###strtold_s
**SRS_CRT_ABSTRACTIONS_21_016: [** The strtof_s must return the float that represents the value in the initial part of the string. If any. **]**
**SRS_CRT_ABSTRACTIONS_21_017: [** The strtof_s must return in endptr a final string of one or more unrecognized characters, including the terminating null character of the input string. **]**
**SRS_CRT_ABSTRACTIONS_21_018: [** The white-space for strtof_s must be one of the characters ' ', '\f', '\n', '\r', '\t', '\v'. **]**
**SRS_CRT_ABSTRACTIONS_21_019: [** The valid sequence for strtof_s starts after the first non-white-space character, followed by an optional positive or negative sign, a number, 'INF', or 'NAN' (ignoring case). **]**
**SRS_CRT_ABSTRACTIONS_21_020: [** If the subject sequence is empty or does not have the expected form, the strtof_s must **not** perform any conversion and must returns 0.0f; the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a NULL pointer. **]**
**SRS_CRT_ABSTRACTIONS_21_021: [** If no conversion could be performed, the strtof_s returns the value 0.0f. **]**
**SRS_CRT_ABSTRACTIONS_21_022: [** If the correct value is outside the range, the strtof_s returns the value plus or minus HUGE_VALF, and errno will receive the value ERANGE. **]**
**SRS_CRT_ABSTRACTIONS_21_023: [** If the string is 'INF' of 'INFINITY' (ignoring case), the strtof_s must return the INFINITY value for float. **]**
**SRS_CRT_ABSTRACTIONS_21_024: [** If the string is 'NAN' or 'NAN(...)' (ignoring case), the strtof_s must return 0.0f and points endptr to the first character after the 'NAN' sequence. **]**
**SRS_CRT_ABSTRACTIONS_21_036: [** If the nptr is NULL, the strtof_s must **not** perform any conversion and must returns 0.0f; endptr must receive NULL, provided that endptr is not a NULL pointer. **]**
### strtold_s
```c
long double strtold_s(const char* nptr, char** endptr)
```
**SRS_CRT_ABSTRACTIONS_21_025: [**The strtold_s must convert the initial portion of the string pointed to by nptr to long double representation.**]**
**SRS_CRT_ABSTRACTIONS_21_026: [**The strtold_s must return the long double that represents the value in the initial part of the string. If any.**]**
**SRS_CRT_ABSTRACTIONS_21_027: [**The strtold_s must return in endptr a final string of one or more unrecognized characters, including the terminating null character of the input string.**]**
**SRS_CRT_ABSTRACTIONS_21_028: [**The white-space for strtold_s must be one of the characters ' ', '\f', '\n', '\r', '\t', '\v'.**]**
**SRS_CRT_ABSTRACTIONS_21_029: [**The valid sequence for strtold_s starts after the first non-white-space character, followed by an optional positive or negative sign, a number, 'INF', or 'NAN' (ignoring case).**]**
**SRS_CRT_ABSTRACTIONS_21_030: [**If the subject sequence is empty or does not have the expected form, the strtold_s must **not** perform any conversion and must returns 0.0; the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a NULL pointer.**]**
**SRS_CRT_ABSTRACTIONS_21_031: [**If no conversion could be performed, the strtold_s returns the value 0.0.**]**
**SRS_CRT_ABSTRACTIONS_21_032: [**If the correct value is outside the range, the strtold_s returns the value plus or minus HUGE_VALL, and errno will receive the value ERANGE.**]**
**SRS_CRT_ABSTRACTIONS_21_033: [**If the string is 'INF' of 'INFINITY' (ignoring case), the strtold_s must return the INFINITY value for long double.**]**
**SRS_CRT_ABSTRACTIONS_21_034: [**If the string is 'NAN' or 'NAN(...)' (ignoring case), the strtold_s must return 0.0 and points endptr to the first character after the 'NAN' sequence.**]**
**SRS_CRT_ABSTRACTIONS_21_037: [**If the nptr is NULL, the strtold_s must **not** perform any conversion and must returns 0.0; endptr must receive NULL, provided that endptr is not a NULL pointer.**]**
**SRS_CRT_ABSTRACTIONS_21_025: [** The strtold_s must convert the initial portion of the string pointed to by nptr to long double representation. **]**
**SRS_CRT_ABSTRACTIONS_21_026: [** The strtold_s must return the long double that represents the value in the initial part of the string. If any. **]**
**SRS_CRT_ABSTRACTIONS_21_027: [** The strtold_s must return in endptr a final string of one or more unrecognized characters, including the terminating null character of the input string. **]**
**SRS_CRT_ABSTRACTIONS_21_028: [** The white-space for strtold_s must be one of the characters ' ', '\f', '\n', '\r', '\t', '\v'. **]**
**SRS_CRT_ABSTRACTIONS_21_029: [** The valid sequence for strtold_s starts after the first non-white-space character, followed by an optional positive or negative sign, a number, 'INF', or 'NAN' (ignoring case). **]**
**SRS_CRT_ABSTRACTIONS_21_030: [** If the subject sequence is empty or does not have the expected form, the strtold_s must **not** perform any conversion and must returns 0.0; the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a NULL pointer. **]**
**SRS_CRT_ABSTRACTIONS_21_031: [** If no conversion could be performed, the strtold_s returns the value 0.0. **]**
**SRS_CRT_ABSTRACTIONS_21_032: [** If the correct value is outside the range, the strtold_s returns the value plus or minus HUGE_VALL, and errno will receive the value ERANGE. **]**
**SRS_CRT_ABSTRACTIONS_21_033: [** If the string is 'INF' of 'INFINITY' (ignoring case), the strtold_s must return the INFINITY value for long double. **]**
**SRS_CRT_ABSTRACTIONS_21_034: [** If the string is 'NAN' or 'NAN(...)' (ignoring case), the strtold_s must return 0.0 and points endptr to the first character after the 'NAN' sequence. **]**
**SRS_CRT_ABSTRACTIONS_21_037: [** If the nptr is NULL, the strtold_s must **not** perform any conversion and must returns 0.0; endptr must receive NULL, provided that endptr is not a NULL pointer. **]**

57
devdoc/doublylinkedlist_requirements.md
Просмотреть файл

@ -1,29 +1,29 @@
DoublyLinkedList Requirements
================
##Overview
## Overview
These functions are the basic linking structures used throughout NT.
They have been publicly available since 1992.
Note that the lists do NOT store any data, by design.
They simply provide a consistent mechanism for linking homogenous items. Also note that no input error checking is provided for this set of APIs.
##References
## References
[http://www.dcl.hpi.uni-potsdam.de/research/WRK/2009/07/single_list_entry-containing_record/](http://www.dcl.hpi.uni-potsdam.de/research/WRK/2009/07/single_list_entry-containing_record/)
##Exposed API
## Exposed API
```c
typedef struct DLIST_ENTRY_TAG
{
struct DLIST_ENTRY_TAG *Flink;
struct DLIST_ENTRY_TAG *Blink;
} DLIST_ENTRY, *PDLIST_ENTRY;
extern void DList_InitializeListHead(PDLIST_ENTRY listHead);
extern int DList_IsListEmpty(const PDLIST_ENTRY listHead);
extern void DList_InsertTailList(PDLIST_ENTRY listHead, PDLIST_ENTRY listEntry);
extern void DList_InsertHeadList(PDLIST_ENTRY listHead, PDLIST_ENTRY entry);
extern void DList_InsertHeadList(PDLIST_ENTRY listHead, PDLIST_ENTRY entry);
extern void DList_AppendTailList(PDLIST_ENTRY listHead, PDLIST_ENTRY ListToAppend);
extern int DList_RemoveEntryList(PDLIST_ENTRY listEntry);
extern PDLIST_ENTRY DList_RemoveHeadList(PDLIST_ENTRY listHead);
@ -31,75 +31,76 @@ extern PDLIST_ENTRY DList_RemoveHeadList(PDLIST_ENTRY listHead);
// Calculate the address of the base of the structure given its type, and an
// address of a field within the structure.
//
#define containingRecord(address, type, field) ((type *)((char *)(address) - offsetof(type,field)))
```
###DList_InitializeListHead
### DList_InitializeListHead
```c
extern void DList_InitializeListHead(PDLIST_ENTRY listHead);
```
**SRS_DLIST_06_005: [**DList_InitializeListHead will initialize the Flink & Blink to the address of the DLIST_ENTRY.**]**
**SRS_DLIST_06_005: [** DList_InitializeListHead will initialize the Flink & Blink to the address of the DLIST_ENTRY. **]**
###DList_IsListEmpty
### DList_IsListEmpty
```c
extern int DList_IsListEmpty(const PDLIST_ENTRY listHead);
```
**SRS_DLIST_06_003: [**DList_IsListEmpty shall return a non-zero value if there are no DLIST_ENTRY's on this list other than the list head.**]**
**SRS_DLIST_06_004: [**DList_IsListEmpty shall return 0 if there is one or more items in the list.**]**
**SRS_DLIST_06_003: [** DList_IsListEmpty shall return a non-zero value if there are no DLIST_ENTRY's on this list other than the list head. **]**
**SRS_DLIST_06_004: [** DList_IsListEmpty shall return 0 if there is one or more items in the list. **]**
Notes:
1. DList_IsListEmpty shall be undefined if the DLIST_ENTRY is not currently part of a list.
2. DList_IsListEmpty shall be undefined if the DLIST_ENTRY has not been initialized as with DList_InitializeListHead.
###DList_InsertTailList
### DList_InsertTailList
```c
extern void DList_InsertTailList(PDLIST_ENTRY listHead, PDLIST_ENTRY listEntry);
```
**SRS_DLIST_06_006: [**DList_InsertTailList shall place the DLIST_ENTRY at the end of the list defined by the listHead parameter.**]**
**SRS_DLIST_06_006: [** DList_InsertTailList shall place the DLIST_ENTRY at the end of the list defined by the listHead parameter. **]**
###DList_InsertHeadList
```c
### DList_InsertHeadList
```c
extern void DList_InsertHeadList(PDLIST_ENTRY listHead, PDLIST_ENTRY entry);
```
```
**SRS_DLIST_02_002: [**DList_InsertHeadList inserts a singular entry in the list having as head listHead after "head".**]** (see diagram below)
**SRS_DLIST_02_002: [** DList_InsertHeadList inserts a singular entry in the list having as head listHead after "head". **]** (see diagram below)
DList_InsertHeadList shall assume listHead and listEntry non-NULL and pointing to existing DLIST_ENTRY structures. Calling DList_InsertHeadList with NULL parameters is undefined behavior.
###DList_AppendTailList
### DList_AppendTailList
```c
extern void DList_AppendTailList(PDLIST_ENTRY listHead, PDLIST_ENTRY ListToAppend);
```
**SRS_DLIST_06_007: [**DList_AppendTailList shall place the list defined by listToAppend at the end of the list defined by the listHead parameter.**]**
**SRS_DLIST_06_007: [** DList_AppendTailList shall place the list defined by listToAppend at the end of the list defined by the listHead parameter. **]**
###DList_RemoveEntryList
### DList_RemoveEntryList
```c
extern int DList_RemoveEntryList(PDLIST_ENTRY listEntry);
```
**SRS_DLIST_06_008: [**DList_RemoveEntryList shall remove a listEntry from whatever list it is properly part of.**]**
**SRS_DLIST_06_008: [** DList_RemoveEntryList shall remove a listEntry from whatever list it is properly part of. **]**
**SRS_DLIST_06_009: [**The remaining list is properly formed.**]**
**SRS_DLIST_06_009: [** The remaining list is properly formed. **]**
**SRS_DLIST_06_010: [**DList_RemoveEntryList shall return non-zero if the remaining list is empty.**]**
**SRS_DLIST_06_010: [** DList_RemoveEntryList shall return non-zero if the remaining list is empty. **]**
**SRS_DLIST_06_011: [**DList_RemoveEntryList shall return zero if the remaining list is NOT empty.**]**
**SRS_DLIST_06_011: [** DList_RemoveEntryList shall return zero if the remaining list is NOT empty. **]**
Notes:
1. If listEntry is NOT part of a list then the result of this function is undefined. Therefore, calling DList_RemoveEntryList twice on the same listEntry is undefined.
2. The Flink & Blink of the listEntry parameter shall be undefined after calling this function
###DList_RemoveHeadList
### DList_RemoveHeadList
```c
extern PDLIST_ENTRY DList_RemoveHeadList(PDLIST_ENTRY listHead);
```
**SRS_DLIST_06_012: [**DList_RemoveHeadList removes the oldest entry from the list defined by the listHead parameter and returns a pointer to that entry.**]**
**SRS_DLIST_06_012: [** DList_RemoveHeadList removes the oldest entry from the list defined by the listHead parameter and returns a pointer to that entry. **]**
**SRS_DLIST_06_013: [**DList_RemoveHeadList shall return listHead if that's the only item in the list.**]**
**SRS_DLIST_06_013: [** DList_RemoveHeadList shall return listHead if that's the only item in the list. **]**
Note: The Flink & Blink of the returned PDLIST_ENTRY shall be undefined.

162
devdoc/gballoc_requirements.md
Просмотреть файл

@ -1,15 +1,15 @@
gballoc requirements
================
##Overview
## Overview
gballoc is a module that is a pass through for the malloc, realloc and free memory management functions described in C99, section 7.20.3.
The pass through has the purpose of tracking memory allocations in order to compute the maximal memory usage of an application using the memory management functions.
##References
## References
[ISO/IEC 9899:TC3]
##Exposed API
## Exposed API
```c
extern int gballoc_init(void);
extern void gballoc_deinit(void);
@ -24,96 +24,134 @@ extern size_t gballoc_getMaximumMemoryUsed(void);
extern size_t gballoc_getCurrentMemoryUsed(void);
```
###gballoc_init
### gballoc_init
```c
extern int gballoc_init(void);
```
**SRS_GBALLOC_01_024: [**gballoc_init shall initialize the gballoc module and return 0 upon success.**]**
**SRS_GBALLOC_01_025: [**Init after Init shall fail and return a non-zero value.**]**
**SRS_GBALLOC_01_026: [**gballoc_Init shall create a lock handle that will be used to make the other gballoc APIs thread-safe.**]**
**SRS_GBALLOC_01_027: [**If the Lock creation fails, gballoc_init shall return a non-zero value.**]**
**SRS_GBALLOC_01_002: [**Upon initialization the total memory used and maximum total memory used tracked by the module shall be set to 0.**]**
###gballoc_deinit
**SRS_GBALLOC_01_024: [** gballoc_init shall initialize the gballoc module and return 0 upon success. **]**
**SRS_GBALLOC_01_025: [** Init after Init shall fail and return a non-zero value. **]**
**SRS_GBALLOC_01_026: [** gballoc_Init shall create a lock handle that will be used to make the other gballoc APIs thread-safe. **]**
**SRS_GBALLOC_01_027: [** If the Lock creation fails, gballoc_init shall return a non-zero value. **]**
**SRS_GBALLOC_01_002: [** Upon initialization the total memory used and maximum total memory used tracked by the module shall be set to 0. **]**
### gballoc_deinit
```c
extern void gballoc_deinit(void);
```
**SRS_GBALLOC_01_028: [**gballoc_deinit shall free all resources allocated by gballoc_init.**]**
**SRS_GBALLOC_01_029: [**if gballoc is not initialized gballoc_deinit shall do nothing.**]**
###gballoc_malloc
**SRS_GBALLOC_01_028: [** gballoc_deinit shall free all resources allocated by gballoc_init. **]**
**SRS_GBALLOC_01_029: [** if gballoc is not initialized gballoc_deinit shall do nothing. **]**
### gballoc_malloc
```c
extern void* gballoc_malloc(size_t size);
```
**SRS_GBALLOC_01_003: [**gballoc_malloc shall call the C99 malloc function and return its result.**]**
**SRS_GBALLOC_01_004: [**If the underlying malloc call is successful, gballoc_malloc shall increment the total memory used with the amount indicated by size.**]**
**SRS_GBALLOC_01_012: [**When the underlying malloc call fails, gballoc_malloc shall return NULL and size should not be counted towards total memory used.**]**
**SRS_GBALLOC_01_013: [**When gballoc_malloc fails allocating memory for its internal use, gballoc_malloc shall return NULL.**]**
**SRS_GBALLOC_01_030: [**gballoc_malloc shall ensure thread safety by using the lock created by gballoc_Init.**]**
**SRS_GBALLOC_01_039: [**If gballoc was not initialized gballoc_malloc shall simply call malloc without any memory tracking being performed.**]**
**SRS_GBALLOC_01_048: [**If acquiring the lock fails, gballoc_malloc shall return NULL.**]**
###gballoc_calloc
**SRS_GBALLOC_01_003: [** gballoc_malloc shall call the C99 malloc function and return its result. **]**
**SRS_GBALLOC_01_004: [** If the underlying malloc call is successful, gballoc_malloc shall increment the total memory used with the amount indicated by size. **]**
**SRS_GBALLOC_01_012: [** When the underlying malloc call fails, gballoc_malloc shall return NULL and size should not be counted towards total memory used. **]**
**SRS_GBALLOC_01_013: [** When gballoc_malloc fails allocating memory for its internal use, gballoc_malloc shall return NULL. **]**
**SRS_GBALLOC_01_030: [** gballoc_malloc shall ensure thread safety by using the lock created by gballoc_Init. **]**
**SRS_GBALLOC_01_039: [** If gballoc was not initialized gballoc_malloc shall simply call malloc without any memory tracking being performed. **]**
**SRS_GBALLOC_01_048: [** If acquiring the lock fails, gballoc_malloc shall return NULL. **]**
### gballoc_calloc
```c
extern void* gballoc_calloc(size_t nmemb, size_t size);
```
**SRS_GBALLOC_01_020: [**gballoc_calloc shall call the C99 calloc function and return its result.**]**
**SRS_GBALLOC_01_021: [**If the underlying calloc call is successful, gballoc_calloc shall increment the total memory used with nmemb*size.**]**
**SRS_GBALLOC_01_022: [**When the underlying calloc call fails, gballoc_calloc shall return NULL and size should not be counted towards total memory used.**]**
**SRS_GBALLOC_01_023: [**When gballoc_calloc fails allocating memory for its internal use, gballoc_calloc shall return NULL.**]**
**SRS_GBALLOC_01_031: [**gballoc_calloc shall ensure thread safety by using the lock created by gballoc_Init**]**
**SRS_GBALLOC_01_040: [**If gballoc was not initialized gballoc_calloc shall simply call calloc without any memory tracking being performed.**]**
**SRS_GBALLOC_01_046: [**If acquiring the lock fails, gballoc_calloc shall return NULL.**]**
**SRS_GBALLOC_01_020: [** gballoc_calloc shall call the C99 calloc function and return its result. **]**
###gballoc_realloc
**SRS_GBALLOC_01_021: [** If the underlying calloc call is successful, gballoc_calloc shall increment the total memory used with nmemb*size. **]**
**SRS_GBALLOC_01_022: [** When the underlying calloc call fails, gballoc_calloc shall return NULL and size should not be counted towards total memory used. **]**
**SRS_GBALLOC_01_023: [** When gballoc_calloc fails allocating memory for its internal use, gballoc_calloc shall return NULL. **]**
**SRS_GBALLOC_01_031: [** gballoc_calloc shall ensure thread safety by using the lock created by gballoc_Init **]**
**SRS_GBALLOC_01_040: [** If gballoc was not initialized gballoc_calloc shall simply call calloc without any memory tracking being performed. **]**
**SRS_GBALLOC_01_046: [** If acquiring the lock fails, gballoc_calloc shall return NULL. **]**
### gballoc_realloc
```c
extern void* gballoc_realloc(void* ptr, size_t size);
```
**SRS_GBALLOC_01_005: [**gballoc_realloc shall call the C99 realloc function and return its result.**]**
**SRS_GBALLOC_01_006: [**If the underlying realloc call is successful, gballoc_realloc shall look up the size associated with the pointer ptr and decrease the total memory used with that size.**]**
**SRS_GBALLOC_01_007: [**If realloc is successful, gballoc_realloc shall also increment the total memory used value tracked by this module.**]**
**SRS_GBALLOC_01_014: [**When the underlying realloc call fails, gballoc_realloc shall return NULL and no change should be made to the counted total memory usage.**]**
**SRS_GBALLOC_01_015: [**When allocating memory used for tracking by gballoc_realloc fails, gballoc_realloc shall return NULL and no change should be made to the counted total memory usage.**]**
**SRS_GBALLOC_01_016: [**When the ptr pointer cannot be found in the pointers tracked by gballoc, gballoc_realloc shall return NULL and the underlying realloc shall not be called.**]**
**SRS_GBALLOC_01_017: [**When ptr is NULL, gballoc_realloc shall call the underlying realloc with ptr being NULL and the realloc result shall be tracked by gballoc.**]**
**SRS_GBALLOC_01_032: [**gballoc_realloc shall ensure thread safety by using the lock created by gballoc_Init.**]**
**SRS_GBALLOC_01_041: [**If gballoc was not initialized gballoc_realloc shall shall simply call realloc without any memory tracking being performed.**]**
**SRS_GBALLOC_01_047: [**If acquiring the lock fails, gballoc_realloc shall return NULL.**]**
**SRS_GBALLOC_01_005: [** gballoc_realloc shall call the C99 realloc function and return its result. **]**
###gballoc_free
**SRS_GBALLOC_01_006: [** If the underlying realloc call is successful, gballoc_realloc shall look up the size associated with the pointer ptr and decrease the total memory used with that size. **]**
**SRS_GBALLOC_01_007: [** If realloc is successful, gballoc_realloc shall also increment the total memory used value tracked by this module. **]**
**SRS_GBALLOC_01_014: [** When the underlying realloc call fails, gballoc_realloc shall return NULL and no change should be made to the counted total memory usage. **]**
**SRS_GBALLOC_01_015: [** When allocating memory used for tracking by gballoc_realloc fails, gballoc_realloc shall return NULL and no change should be made to the counted total memory usage. **]**
**SRS_GBALLOC_01_016: [** When the ptr pointer cannot be found in the pointers tracked by gballoc, gballoc_realloc shall return NULL and the underlying realloc shall not be called. **]**
**SRS_GBALLOC_01_017: [** When ptr is NULL, gballoc_realloc shall call the underlying realloc with ptr being NULL and the realloc result shall be tracked by gballoc. **]**
**SRS_GBALLOC_01_032: [** gballoc_realloc shall ensure thread safety by using the lock created by gballoc_Init. **]**
**SRS_GBALLOC_01_041: [** If gballoc was not initialized gballoc_realloc shall shall simply call realloc without any memory tracking being performed. **]**
**SRS_GBALLOC_01_047: [** If acquiring the lock fails, gballoc_realloc shall return NULL. **]**
### gballoc_free
```c
extern void gballoc_free(void* ptr);
```
**SRS_GBALLOC_01_008: [**gballoc_free shall call the C99 free function.**]**
**SRS_GBALLOC_01_009: [**gballoc_free shall also look up the size associated with the ptr pointer and decrease the total memory used with the associated size amount.**]**
**SRS_GBALLOC_01_019: [**When the ptr pointer cannot be found in the pointers tracked by gballoc, gballoc_free shall not free any memory.**]**
**SRS_GBALLOC_01_033: [**gballoc_free shall ensure thread safety by using the lock created by gballoc_Init.**]**
**SRS_GBALLOC_01_042: [**If gballoc was not initialized gballoc_free shall shall simply call free.**]**
**SRS_GBALLOC_01_049: [**If acquiring the lock fails, gballoc_free shall do nothing.**]**
**SRS_GBALLOC_01_008: [** gballoc_free shall call the C99 free function. **]**
###gballoc_getMaximumMemoryUsed
**SRS_GBALLOC_01_009: [** gballoc_free shall also look up the size associated with the ptr pointer and decrease the total memory used with the associated size amount. **]**
**SRS_GBALLOC_01_019: [** When the ptr pointer cannot be found in the pointers tracked by gballoc, gballoc_free shall not free any memory. **]**
**SRS_GBALLOC_01_033: [** gballoc_free shall ensure thread safety by using the lock created by gballoc_Init. **]**
**SRS_GBALLOC_01_042: [** If gballoc was not initialized gballoc_free shall shall simply call free. **]**
**SRS_GBALLOC_01_049: [** If acquiring the lock fails, gballoc_free shall do nothing. **]**
### gballoc_getMaximumMemoryUsed
```c
extern size_t gballoc_getMaximumMemoryUsed(void);
```
**SRS_GBALLOC_01_010: [**gballoc_getMaximumMemoryUsed shall return the maximum amount of total memory used recorded since the module initialization.**]**
**SRS_GBALLOC_01_011: [**The maximum total memory used shall be the maximum of the total memory used at any point.**]**
**SRS_GBALLOC_01_034: [**gballoc_getMaximumMemoryUsed shall ensure thread safety by using the lock created by gballoc_Init.**]**
**SRS_GBALLOC_01_038: [**If gballoc was not initialized gballoc_getMaximumMemoryUsed shall return MAX_INT_SIZE.**]**
**SRS_GBALLOC_01_050: [**If the lock cannot be acquired, gballoc_getMaximumMemoryUsed shall return SIZE_MAX.**]**
###gballoc_getCurrentMemoryUsed
**SRS_GBALLOC_01_010: [** gballoc_getMaximumMemoryUsed shall return the maximum amount of total memory used recorded since the module initialization. **]**
**SRS_GBALLOC_01_011: [** The maximum total memory used shall be the maximum of the total memory used at any point. **]**
**SRS_GBALLOC_01_034: [** gballoc_getMaximumMemoryUsed shall ensure thread safety by using the lock created by gballoc_Init. **]**
**SRS_GBALLOC_01_038: [** If gballoc was not initialized gballoc_getMaximumMemoryUsed shall return MAX_INT_SIZE. **]**
**SRS_GBALLOC_01_050: [** If the lock cannot be acquired, gballoc_getMaximumMemoryUsed shall return SIZE_MAX. **]**
### gballoc_getCurrentMemoryUsed
```c
extern size_t gballoc_getCurrentMemoryUsed(void);
```
**SRS_GBALLOC_02_001: [**gballoc_getCurrentMemoryUsed shall return the currently used memory size.**]**
**SRS_GBALLOC_01_036: [**gballoc_getCurrentMemoryUsed shall ensure thread safety by using the lock created by gballoc_Init.**]**
**SRS_GBALLOC_01_044: [**If gballoc was not initialized gballoc_getCurrentMemoryUsed shall return SIZE_MAX.**]**
**SRS_GBALLOC_01_051: [**If the lock cannot be acquired, gballoc_getCurrentMemoryUsed shall return SIZE_MAX.**]**
**SRS_GBALLOC_02_001: [** gballoc_getCurrentMemoryUsed shall return the currently used memory size. **]**
**SRS_GBALLOC_01_036: [** gballoc_getCurrentMemoryUsed shall ensure thread safety by using the lock created by gballoc_Init. **]**
**SRS_GBALLOC_01_044: [** If gballoc was not initialized gballoc_getCurrentMemoryUsed shall return SIZE_MAX. **]**
**SRS_GBALLOC_01_051: [** If the lock cannot be acquired, gballoc_getCurrentMemoryUsed shall return SIZE_MAX. **]**

99
devdoc/http_proxy_io_requirements.md
Просмотреть файл

@ -18,7 +18,7 @@ MOCKABLE_FUNCTION(, const IO_INTERFACE_DESCRIPTION*, http_proxy_io_get_interface
```
### http_proxy_io_create
### http_proxy_io_create
`http_proxy_io_create` is the implementation provided via `http_proxy_io_get_interface_description` for the `concrete_io_create` member.
@ -27,22 +27,36 @@ CONCRETE_IO_HANDLE http_proxy_io_create(void* io_create_parameters);
```
**SRS_HTTP_PROXY_IO_01_001: [** `http_proxy_io_create` shall create a new instance of the HTTP proxy IO. **]**
**SRS_HTTP_PROXY_IO_01_002: [** If `io_create_parameters` is NULL, `http_proxy_io_create` shall fail and return NULL. **]**
**SRS_HTTP_PROXY_IO_01_003: [** `io_create_parameters` shall be used as an `HTTP_PROXY_IO_CONFIG*`. **]**
**SRS_HTTP_PROXY_IO_01_004: [** If the `hostname` or `proxy_hostname` member is NULL, then `http_proxy_io_create` shall fail and return NULL. **]**
**SRS_HTTP_PROXY_IO_01_005: [** `http_proxy_io_create` shall copy the `hostname`, `port`, `username` and `password` values for later use when the actual CONNECT is performed. **]**
**SRS_HTTP_PROXY_IO_01_006: [** `hostname` and `proxy_hostname`, `username` and `password` shall be copied by calling `mallocAndStrcpy_s`. **]**
**SRS_HTTP_PROXY_IO_01_094: [** `username` and `password` shall be optional. **]**
**SRS_HTTP_PROXY_IO_01_095: [** If one of the fields `username` and `password` is non-NULL, then the other has to be also non-NULL, otherwise `http_proxy_io_create` shall fail and return NULL. **]**
**SRS_HTTP_PROXY_IO_01_007: [** If `mallocAndStrcpy_s` fails then `http_proxy_io_create` shall fail and return NULL. **]**
**SRS_HTTP_PROXY_IO_01_009: [** `http_proxy_io_create` shall create a new socket IO by calling `xio_create` with the arguments: **]**
**SRS_HTTP_PROXY_IO_01_010: [** - `io_interface_description` shall be set to the result of `socketio_get_interface_description`. **]**
**SRS_HTTP_PROXY_IO_01_011: [** - `xio_create_parameters` shall be set to a `SOCKETIO_CONFIG*` where `hostname` is set to the `proxy_hostname` member of `io_create_parameters` and `port` is set to the `proxy_port` member of `io_create_parameters`. **]**
**SRS_HTTP_PROXY_IO_01_050: [** If `socketio_get_interface_description` fails, `http_proxy_io_create` shall fail and return NULL. **]**
**SRS_HTTP_PROXY_IO_01_012: [** If `xio_create` fails, `http_proxy_io_create` shall fail and return NULL. **]**
**SRS_HTTP_PROXY_IO_01_008: [** When `http_proxy_io_create` fails, all allocated resources up to that point shall be freed. **]**
### http_proxy_io_destroy
### http_proxy_io_destroy
`http_proxy_io_destroy` is the implementation provided via `http_proxy_io_get_interface_description` for the `concrete_io_destroy` member.
@ -51,11 +65,14 @@ void http_proxy_io_destroy(CONCRETE_IO_HANDLE http_proxy_io);
```
**SRS_HTTP_PROXY_IO_01_013: [** `http_proxy_io_destroy` shall free the HTTP proxy IO instance indicated by `http_proxy_io`. **]**
**SRS_HTTP_PROXY_IO_01_014: [** If `http_proxy_io` is NULL, `http_proxy_io_destroy` shall do nothing. **]**
**SRS_HTTP_PROXY_IO_01_015: [** `http_proxy_io_destroy` should close the IO if it was open before freeing all the resources. **]**
**SRS_HTTP_PROXY_IO_01_016: [** `http_proxy_io_destroy` shall destroy the underlying IO created in `http_proxy_io_create` by calling `xio_destroy`. **]**
### http_proxy_io_open
### http_proxy_io_open
`http_proxy_io_open` is the implementation provided via `http_proxy_io_get_interface_description` for the `concrete_io_open` member.
@ -64,13 +81,18 @@ int http_proxy_io_open(CONCRETE_IO_HANDLE http_proxy_io, ON_IO_OPEN_COMPLETE on_
```
**SRS_HTTP_PROXY_IO_01_017: [** `http_proxy_io_open` shall open the HTTP proxy IO and on success it shall return 0. **]**
**SRS_HTTP_PROXY_IO_01_018: [** If any of the arguments `http_proxy_io`, `on_io_open_complete`, `on_bytes_received` or `on_io_error` are NULL then `http_proxy_io_open` shall return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_019: [** `http_proxy_io_open` shall open the underlying IO by calling `xio_open` on the underlying IO handle created in `http_proxy_io_create`, while passing to it the callbacks `on_underlying_io_open_complete`, `on_underlying_io_bytes_received` and `on_underlying_io_error`. **]**
**SRS_HTTP_PROXY_IO_01_020: [** If `xio_open` fails, then `http_proxy_io_open` shall return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_021: [** If `http_proxy_io_open` is called while the IO was already open, `http_proxy_io_open` shall fail and return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_051: [** The arguments `on_io_open_complete_context`, `on_bytes_received_context` and `on_io_error_context` shall be allowed to be NULL. **]**
### http_proxy_io_close
### http_proxy_io_close
`http_proxy_io_close` is the implementation provided via `http_proxy_io_get_interface_description` for the `concrete_io_close` member.
@ -79,17 +101,26 @@ int http_proxy_io_close(CONCRETE_IO_HANDLE http_proxy_io, ON_IO_CLOSE_COMPLETE o
```
**SRS_HTTP_PROXY_IO_01_022: [** `http_proxy_io_close` shall close the HTTP proxy IO and on success it shall return 0. **]**
**SRS_HTTP_PROXY_IO_01_023: [** If the argument `http_proxy_io` is NULL, `http_proxy_io_close` shall fail and return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_024: [** `http_proxy_io_close` shall close the underlying IO by calling `xio_close` on the IO handle create in `http_proxy_io_create`, while passing to it the `on_underlying_io_close_complete` callback. **]**
**SRS_HTTP_PROXY_IO_01_025: [** If `xio_close` fails, `http_proxy_io_close` shall fail and return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_026: [** The `on_io_close_complete` and `on_io_close_complete_context` arguments shall be saved for later use. **]**
**SRS_HTTP_PROXY_IO_01_027: [** If `http_proxy_io_close` is called when not open, `http_proxy_io_close` shall fail and return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_028: [** `on_io_close_complete` shall be allowed to be NULL. **]**
**SRS_HTTP_PROXY_IO_01_052: [** `on_io_close_complete_context` shall be allowed to be NULL. **]**
**SRS_HTTP_PROXY_IO_01_053: [** `http_proxy_io_close` while OPENING shall trigger the `on_io_open_complete` callback with `IO_OPEN_CANCELLED`. **]**
**SRS_HTTP_PROXY_IO_01_054: [** `http_proxy_io_close` while OPENING shall fail and return a non-zero value. **]**
### http_proxy_io_send
### http_proxy_io_send
`http_proxy_io_send` is the implementation provided via `http_proxy_io_get_interface_description` for the `concrete_io_send` member.
@ -98,15 +129,22 @@ int http_proxy_io_send(CONCRETE_IO_HANDLE http_proxy_io, const void* buffer, siz
```
**SRS_HTTP_PROXY_IO_01_029: [** `http_proxy_io_send` shall send the `size` bytes pointed to by `buffer` and on success it shall return 0. **]**
**SRS_HTTP_PROXY_IO_01_030: [** If any of the arguments `http_proxy_io` or `buffer` is NULL, `http_proxy_io_send` shall fail and return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_031: [** If `size` is 0, `http_proxy_io_send` shall fail and return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_032: [** `on_send_complete` shall be allowed to be NULL. **]**
**SRS_HTTP_PROXY_IO_01_033: [** `http_proxy_io_send` shall send the bytes by calling `xio_send` on the underlying IO created in `http_proxy_io_create` and passing `buffer` and `size` as arguments. **]**
**SRS_HTTP_PROXY_IO_01_034: [** If `http_proxy_io_send` is called when the IO is not open, `http_proxy_io_send` shall fail and return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_035: [** If the IO is in an error state (an error was reported through the `on_io_error` callback), `http_proxy_io_send` shall fail and return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_055: [** If `xio_send` fails, `http_proxy_io_send` shall fail and return a non-zero value. **]**
### http_proxy_io_dowork
### http_proxy_io_dowork
`http_proxy_io_dowork` is the implementation provided via `http_proxy_io_get_interface_description` for the `concrete_io_dowork` member.
@ -115,10 +153,12 @@ void http_proxy_io_dowork(CONCRETE_IO_HANDLE http_proxy_io)
```
**SRS_HTTP_PROXY_IO_01_037: [** `http_proxy_io_dowork` shall call `xio_dowork` on the underlying IO created in `http_proxy_io_create`. **]**
**SRS_HTTP_PROXY_IO_01_038: [** If the `http_proxy_io` argument is NULL, `http_proxy_io_dowork` shall do nothing. **]**
**SRS_HTTP_PROXY_IO_01_039: [** If the IO is not open (no open has been called or the IO has been closed) then `http_proxy_io_dowork` shall do nothing. **]**
### http_proxy_io_set_option
### http_proxy_io_set_option
`http_proxy_io_set_option` is the implementation provided via `http_proxy_io_get_interface_description` for the `concrete_io_setoption` member.
@ -127,16 +167,20 @@ int http_proxy_io_set_option(CONCRETE_IO_HANDLE http_proxy_io, const char* optio
```
**SRS_HTTP_PROXY_IO_01_040: [** If any of the arguments `http_proxy_io` or `option_name` is NULL, `http_proxy_io_set_option` shall return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_042: [** If the option was handled by `http_proxy_io_set_option` or the underlying IO, then `http_proxy_io_set_option` shall return 0. **]**
**SRS_HTTP_PROXY_IO_01_043: [** If the `option_name` argument indicates an option that is not handled by `http_proxy_io_set_option`, then `xio_setoption` shall be called on the underlying IO created in `http_proxy_io_create`, passing the option name and value to it. **]**
**SRS_HTTP_PROXY_IO_01_044: [** if `xio_setoption` fails, `http_proxy_io_set_option` shall return a non-zero value. **]**
**SRS_HTTP_PROXY_IO_01_056: [** The `value` argument shall be allowed to be NULL. **]**
Options that shall be handled by HTTP proxy IO:
**SRS_HTTP_PROXY_IO_01_045: [** None. **]**
### http_proxy_io_retrieve_options
### http_proxy_io_retrieve_options
`http_proxy_io_retrieve_options` is the implementation provided via `http_proxy_io_get_interface_description` for the `concrete_io_retrieveoptions` member.
@ -145,10 +189,12 @@ static OPTIONHANDLER_HANDLE http_proxy_io_retrieve_options(CONCRETE_IO_HANDLE ht
```
**SRS_HTTP_PROXY_IO_01_046: [** `http_proxy_io_retrieve_options` shall return an `OPTIONHANDLER_HANDLE` obtained by calling `xio_retrieveoptions` on the underlying IO created in `http_proxy_io_create`. **]**
**SRS_HTTP_PROXY_IO_01_047: [** If the parameter `http_proxy_io` is NULL then `http_proxy_io_retrieve_options` shall fail and return NULL. **]**
**SRS_HTTP_PROXY_IO_01_048: [** If `xio_retrieveoptions` fails, `http_proxy_io_retrieve_options` shall return NULL. **]**
### http_proxy_io_get_interface_description
### http_proxy_io_get_interface_description
```c
extern const IO_INTERFACE_DESCRIPTION* http_proxy_io_get_interface_description(void);
@ -156,46 +202,72 @@ extern const IO_INTERFACE_DESCRIPTION* http_proxy_io_get_interface_description(v
**SRS_HTTP_PROXY_IO_01_049: [** `http_proxy_io_get_interface_description` shall return a pointer to an `IO_INTERFACE_DESCRIPTION` structure that contains pointers to the functions: `http_proxy_io_retrieve_options`, `http_proxy_io_retrieve_create`, `http_proxy_io_destroy`, `http_proxy_io_open`, `http_proxy_io_close`, `http_proxy_io_send` and `http_proxy_io_dowork`. **]**
### on_underlying_io_open_complete
### on_underlying_io_open_complete
**SRS_HTTP_PROXY_IO_01_057: [** When `on_underlying_io_open_complete` is called, the `http_proxy_io` shall send the CONNECT request constructed per RFC 2817: **]**
**SRS_HTTP_PROXY_IO_01_078: [** When `on_underlying_io_open_complete` is called with `IO_OPEN_ERROR`, the `on_open_complete` callback shall be triggered with `IO_OPEN_ERROR`, passing also the `on_open_complete_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_079: [** When `on_underlying_io_open_complete` is called with `IO_OPEN_CANCELLED`, the `on_open_complete` callback shall be triggered with `IO_OPEN_CANCELLED`, passing also the `on_open_complete_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_059: [** - If `username` and `password` have been specified in the arguments passed to `http_proxy_io_create`, then the header `Proxy-Authorization` shall be added to the request. **]**
**SRS_HTTP_PROXY_IO_01_060: [** - The value of `Proxy-Authorization` shall be the constructed according to RFC 2617. **]**
**SRS_HTTP_PROXY_IO_01_061: [** Encoding to Base64 shall be done by calling `Base64_Encode_Bytes`. **]**
**SRS_HTTP_PROXY_IO_01_062: [** If any failure is encountered while constructing the request, the `on_open_complete` callback shall be triggered with `IO_OPEN_ERROR`, passing also the `on_open_complete_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_063: [** The request shall be sent by calling `xio_send` and passing NULL as `on_send_complete` callback. **]**
**SRS_HTTP_PROXY_IO_01_064: [** If `xio_send` fails, the `on_open_complete` callback shall be triggered with `IO_OPEN_ERROR`, passing also the `on_open_complete_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_076: [** When `on_underlying_io_open_complete` is called while waiting for the CONNECT reply, the `on_open_complete` callback shall be triggered with `IO_OPEN_ERROR`, passing also the `on_open_complete_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_077: [** When `on_underlying_io_open_complete` is called in after OPEN has completed, the `on_io_error` callback shall be triggered passing the `on_io_error_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_081: [** `on_underlying_io_open_complete` called with NULL context shall do nothing. **]**
### on_underlying_io_bytes_received
### on_underlying_io_bytes_received
**SRS_HTTP_PROXY_IO_01_065: [** When bytes are received and the response to the CONNECT request was not yet received, the bytes shall be accumulated until a double new-line is detected. **]**
**SRS_HTTP_PROXY_IO_01_066: [** When a double new-line is detected the response shall be parsed in order to extract the status code. **]**
**SRS_HTTP_PROXY_IO_01_067: [** If allocating memory for the buffered bytes fails, the `on_open_complete` callback shall be triggered with `IO_OPEN_ERROR`, passing also the `on_open_complete_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_068: [** If parsing the CONNECT response fails, the `on_open_complete` callback shall be triggered with `IO_OPEN_ERROR`, passing also the `on_open_complete_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_069: [** Any successful (2xx) response to a CONNECT request indicates that the proxy has established a connection to the requested host and port, and has switched to tunneling the current connection to that server connection. **]**
**SRS_HTTP_PROXY_IO_01_070: [** When a success status code is parsed, the `on_open_complete` callback shall be triggered with `IO_OPEN_OK`, passing also the `on_open_complete_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_071: [** If the status code is not successful, the `on_open_complete` callback shall be triggered with `IO_OPEN_ERROR`, passing also the `on_open_complete_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_072: [** Any bytes that are extra (not consumed by the CONNECT response), shall be indicated as received by calling the `on_bytes_received` callback and passing the `on_bytes_received_context` as context argument. **]**
**SRS_HTTP_PROXY_IO_01_073: [** Once a success status code was parsed, the IO shall be OPEN. **]**
**SRS_HTTP_PROXY_IO_01_074: [** If `on_underlying_io_bytes_received` is called while OPEN, all bytes shall be indicated as received by calling the `on_bytes_received` callback and passing the `on_bytes_received_context` as context argument. **]**
**SRS_HTTP_PROXY_IO_01_080: [** If `on_underlying_io_bytes_received` is called while the underlying IO is being opened, the `on_open_complete` callback shall be triggered with `IO_OPEN_ERROR`, passing also the `on_open_complete_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_082: [** `on_underlying_io_bytes_received` called with NULL context shall do nothing. **]**
### on_underlying_io_close_complete
### on_underlying_io_close_complete
**SRS_HTTP_PROXY_IO_01_083: [** `on_underlying_io_close_complete` while CLOSING shall call the `on_io_close_complete` callback, passing to it the `on_io_close_complete_context` as `context` argument. **]**
**SRS_HTTP_PROXY_IO_01_084: [** `on_underlying_io_close_complete` called with NULL context shall do nothing. **]**
**SRS_HTTP_PROXY_IO_01_086: [** If the `on_io_close_complete` callback passed to `http_proxy_io_close` was NULL, no callback shall be triggered. **]**
### on_underlying_io_error
### on_underlying_io_error
**SRS_HTTP_PROXY_IO_01_087: [** If the `on_underlying_io_error` callback is called while OPENING, the `on_open_complete` callback shall be triggered with `IO_OPEN_ERROR`, passing also the `on_open_complete_context` argument as `context`. **]**
**SRS_HTTP_PROXY_IO_01_088: [** `on_underlying_io_error` called with NULL context shall do nothing. **]**
**SRS_HTTP_PROXY_IO_01_089: [** If the `on_underlying_io_error` callback is called while the IO is OPEN, the `on_io_error` callback shall be called with the `on_io_error_context` argument as `context`. **]**
## RFC 2817 relevant part
@ -269,6 +341,7 @@ extern const IO_INTERFACE_DESCRIPTION* http_proxy_io_get_interface_description(v
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
A client SHOULD assume that all paths at or deeper than the depth of the last symbolic element in the path field of the Request-URI also are within the protection space specified by the Basic realm value of the current challenge.
**SRS_HTTP_PROXY_IO_01_092: [** A client MAY preemptively send the corresponding Authorization header with requests for resources in that space without receipt of another challenge from the server. **]**
Similarly, when a client sends a request to a proxy, it may reuse a userid and password in the Proxy-Authorization header field without receiving another challenge from the proxy server.
See section 4 for security considerations associated with Basic authentication.

257
devdoc/httpapi_compact_requirements.md
Просмотреть файл

@ -135,7 +135,7 @@ MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_SetOption, HTTP_HANDLE, handle, cons
*/
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_CloneOption, const char*, optionName, const void*, value, const void**, savedValue);
```
**]**
**]**
**SRS_HTTPAPI_COMPACT_21_002: [** The httpapi_compact shall support the http requests:
```c
@ -151,7 +151,7 @@ MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_CloneOption, const char*, optionName
*/
DEFINE_ENUM(HTTPAPI_REQUEST_TYPE, HTTPAPI_REQUEST_TYPE_VALUES);
```
**]**
**]**
**SRS_HTTPAPI_COMPACT_21_003: [** The httpapi_compact shall return error codes defined by HTTPAPI_RESULT:
```c
@ -181,20 +181,22 @@ HTTPAPI_SET_TIMEOUTS_FAILED \
*/
DEFINE_ENUM(HTTPAPI_RESULT, HTTPAPI_RESULT_VALUES);
```
**]**
**]**
### HTTPAPI_Init
### HTTPAPI_Init
```c
HTTPAPI_RESULT HTTPAPI_Init(void);
```
**SRS_HTTPAPI_COMPACT_21_004: [** The HTTPAPI_Init shall allocate all memory to control the http protocol. **]**
**SRS_HTTPAPI_COMPACT_21_006: [** If HTTPAPI_Init succeed allocating all the needed memory, it shall return HTTPAPI_OK. **]**
**SRS_HTTPAPI_COMPACT_21_004: [** The HTTPAPI_Init shall allocate all memory to control the http protocol. **]**
**SRS_HTTPAPI_COMPACT_21_006: [** If HTTPAPI_Init succeed allocating all the needed memory, it shall return HTTPAPI_OK. **]**
**SRS_HTTPAPI_COMPACT_21_007: [** If there is not enough memory to control the http protocol, the HTTPAPI_Init shall return HTTPAPI_ALLOC_FAILED. **]**
### HTTPAPI_Deinit
### HTTPAPI_Deinit
```c
void HTTPAPI_Deinit(void);
```
@ -202,37 +204,52 @@ void HTTPAPI_Deinit(void);
**SRS_HTTPAPI_COMPACT_21_009: [** The HTTPAPI_Init shall release all memory allocated by the httpapi_compact. **]**
### HTTPAPI_CreateConnection
### HTTPAPI_CreateConnection
```c
HTTP_HANDLE HTTPAPI_CreateConnection(const char* hostName);
```
**SRS_HTTPAPI_COMPACT_21_011: [** The HTTPAPI_CreateConnection shall create an http connection to the host specified by the hostName parameter. **]**
**SRS_HTTPAPI_COMPACT_21_012: [** The HTTPAPI_CreateConnection shall return a non-NULL handle on success. **]**
**SRS_HTTPAPI_COMPACT_21_013: [** If there is not enough memory to control the http connection, the HTTPAPI_CreateConnection shall return NULL as the handle. **]**
**SRS_HTTPAPI_COMPACT_21_014: [** If the hostName is NULL, the HTTPAPI_CreateConnection shall return NULL as the handle. **]**
**SRS_HTTPAPI_COMPACT_21_015: [** If the hostName is empty, the HTTPAPI_CreateConnection shall return NULL as the handle. **]**
**SRS_HTTPAPI_COMPACT_21_011: [** The HTTPAPI_CreateConnection shall create an http connection to the host specified by the hostName parameter. **]**
**SRS_HTTPAPI_COMPACT_21_012: [** The HTTPAPI_CreateConnection shall return a non-NULL handle on success. **]**
**SRS_HTTPAPI_COMPACT_21_013: [** If there is not enough memory to control the http connection, the HTTPAPI_CreateConnection shall return NULL as the handle. **]**
**SRS_HTTPAPI_COMPACT_21_014: [** If the hostName is NULL, the HTTPAPI_CreateConnection shall return NULL as the handle. **]**
**SRS_HTTPAPI_COMPACT_21_015: [** If the hostName is empty, the HTTPAPI_CreateConnection shall return NULL as the handle. **]**
**SRS_HTTPAPI_COMPACT_21_016: [** If the HTTPAPI_CreateConnection failed to create the connection, it shall return NULL as the handle. **]**
### HTTPAPI_CloseConnection
### HTTPAPI_CloseConnection
```c
void HTTPAPI_CloseConnection(HTTP_HANDLE handle);
```
**SRS_HTTPAPI_COMPACT_21_017: [** The HTTPAPI_CloseConnection shall close the connection previously created in HTTPAPI_ExecuteRequest. **]**
**SRS_HTTPAPI_COMPACT_21_076: [** After close the connection, The HTTPAPI_CloseConnection shall destroy the connection previously created in HTTPAPI_CreateConnection. **]**
**SRS_HTTPAPI_COMPACT_21_018: [** If there is a certificate associated to this connection, the HTTPAPI_CloseConnection shall free all allocated memory for the certificate. **]**
**SRS_HTTPAPI_COMPACT_06_001: [** If there is a x509 client certificate associated to this connection, the HTTAPI_CloseConnection shall free all allocated memory for the certificate. **]**
**SRS_HTTPAPI_COMPACT_06_002: [** If there is a x509 client private key associated to this connection, then HTTP_CloseConnection shall free all the allocated memory for the private key. **]**
**SRS_HTTPAPI_COMPACT_21_019: [** If there is no previous connection, the HTTPAPI_CloseConnection shall not do anything. **]**
**SRS_HTTPAPI_COMPACT_21_020: [** If the connection handle is NULL, the HTTPAPI_CloseConnection shall not do anything. **]**
**SRS_HTTPAPI_COMPACT_21_084: [** The HTTPAPI_CloseConnection shall wait, at least, 10 seconds for the SSL close process. **]**
**SRS_HTTPAPI_COMPACT_21_085: [** If the HTTPAPI_CloseConnection retries 10 seconds to close the connection without success, it shall destroy the connection anyway. **]**
**SRS_HTTPAPI_COMPACT_21_086: [** The HTTPAPI_CloseConnection shall wait, at least, 100 milliseconds between retries. **]**
**SRS_HTTPAPI_COMPACT_21_017: [** The HTTPAPI_CloseConnection shall close the connection previously created in HTTPAPI_ExecuteRequest. **]**
**SRS_HTTPAPI_COMPACT_21_076: [** After close the connection, The HTTPAPI_CloseConnection shall destroy the connection previously created in HTTPAPI_CreateConnection. **]**
**SRS_HTTPAPI_COMPACT_21_018: [** If there is a certificate associated to this connection, the HTTPAPI_CloseConnection shall free all allocated memory for the certificate. **]**
**SRS_HTTPAPI_COMPACT_06_001: [** If there is a x509 client certificate associated to this connection, the HTTAPI_CloseConnection shall free all allocated memory for the certificate. **]**
**SRS_HTTPAPI_COMPACT_06_002: [** If there is a x509 client private key associated to this connection, then HTTP_CloseConnection shall free all the allocated memory for the private key. **]**
**SRS_HTTPAPI_COMPACT_21_019: [** If there is no previous connection, the HTTPAPI_CloseConnection shall not do anything. **]**
**SRS_HTTPAPI_COMPACT_21_020: [** If the connection handle is NULL, the HTTPAPI_CloseConnection shall not do anything. **]**
**SRS_HTTPAPI_COMPACT_21_084: [** The HTTPAPI_CloseConnection shall wait, at least, 10 seconds for the SSL close process. **]**
**SRS_HTTPAPI_COMPACT_21_085: [** If the HTTPAPI_CloseConnection retries 10 seconds to close the connection without success, it shall destroy the connection anyway. **]**
**SRS_HTTPAPI_COMPACT_21_086: [** The HTTPAPI_CloseConnection shall wait, at least, 100 milliseconds between retries. **]**
**SRS_HTTPAPI_COMPACT_21_087: [** If the xio return anything different than 0, the HTTPAPI_CloseConnection shall destroy the connection anyway. **]**
### HTTPAPI_ExecuteRequest
### HTTPAPI_ExecuteRequest
```c
HTTPAPI_RESULT HTTPAPI_ExecuteRequest(HTTP_HANDLE handle, HTTPAPI_REQUEST_TYPE requestType, const char* relativePath,
HTTP_HEADERS_HANDLE httpHeadersHandle, const unsigned char* content,
@ -240,82 +257,144 @@ HTTPAPI_RESULT HTTPAPI_ExecuteRequest(HTTP_HANDLE handle, HTTPAPI_REQUEST_TYPE r
HTTP_HEADERS_HANDLE responseHeadersHandle, BUFFER_HANDLE responseContent);
```
**SRS_HTTPAPI_COMPACT_21_021: [** The HTTPAPI_ExecuteRequest shall execute the http communtication with the provided host, sending a request and reciving the response. **]**
**SRS_HTTPAPI_COMPACT_21_022: [** If a Certificate was provided, the HTTPAPI_ExecuteRequest shall set this option on the transport layer. **]**
**SRS_HTTPAPI_COMPACT_21_023: [** If the transport failed setting the Certificate, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_SET_OPTION_FAILED. **]**
**SRS_HTTPAPI_COMPACT_06_003: [** If the x509 client certificate is provided, the HTTPAPI_ExecuteRequest shall set this option on the transport layer. **]**
**SRS_HTTPAPI_COMPACT_06_005: [** If the transport failed setting the client certificate, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_SET_OPTION_FAILED. **]**
**SRS_HTTPAPI_COMPACT_06_004: [** If the x509 client certificate private key is provided, the HTTPAPI_ExecuteRequest shall set this optionon the transport layer. **]**
**SRS_HTTPAPI_COMPACT_06_006: [** If the transport failed setting the client certificate private key, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_SET_OPTION_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_024: [** The HTTPAPI_ExecuteRequest shall open the transport connection with the host to send the request. **]**
**SRS_HTTPAPI_COMPACT_21_025: [** If the open process failed, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_OPEN_REQUEST_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_026: [** If the open process succeed, the HTTPAPI_ExecuteRequest shall send the request message to the host. **]**
**SRS_HTTPAPI_COMPACT_21_027: [** If the HTTPAPI_ExecuteRequest cannot create a buffer to send the request, it shall not send any request and return HTTPAPI_STRING_PROCESSING_ERROR. **]**
**SRS_HTTPAPI_COMPACT_21_028: [** If the HTTPAPI_ExecuteRequest cannot send the request header, it shall return HTTPAPI_HTTP_HEADERS_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_029: [** If the HTTPAPI_ExecuteRequest cannot send the buffer with the request, it shall return HTTPAPI_SEND_REQUEST_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_030: [** At the end of the transmission, the HTTPAPI_ExecuteRequest shall receive the response from the host. **]**
**SRS_HTTPAPI_COMPACT_21_032: [** If the HTTPAPI_ExecuteRequest cannot read the message with the request result, it shall return HTTPAPI_READ_DATA_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_033: [** If the whole process succeed, the HTTPAPI_ExecuteRequest shall retur HTTPAPI_OK. **]**
**SRS_HTTPAPI_COMPACT_21_034: [** If there is no previous connection, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_035: [** The HTTPAPI_ExecuteRequest shall execute resquest for types `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. **]**
**SRS_HTTPAPI_COMPACT_21_036: [** The request type shall be provided in the parameter requestType. **]**
**SRS_HTTPAPI_COMPACT_21_037: [** If the request type is unknown, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_038: [** The HTTPAPI_ExecuteRequest shall execute the resquest for the path in relativePath parameter. **]**
**SRS_HTTPAPI_COMPACT_21_039: [** If the relativePath is NULL or invalid, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_040: [** The request shall contain the http header provided in httpHeadersHandle parameter. **]**
**SRS_HTTPAPI_COMPACT_21_041: [** If the httpHeadersHandle is NULL or invalid, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_042: [** The request can contain the a content message, provided in content parameter. **]**
**SRS_HTTPAPI_COMPACT_21_043: [** If the content is NULL, the HTTPAPI_ExecuteRequest shall send the request without content. **]**
**SRS_HTTPAPI_COMPACT_21_044: [** If the content is not NULL, the number of bytes in the content shall be provided in contentLength parameter. **]**
**SRS_HTTPAPI_COMPACT_21_045: [** If the contentLength is lower than one, the HTTPAPI_ExecuteRequest shall send the request without content. **]**
**SRS_HTTPAPI_COMPACT_21_046: [** The HTTPAPI_ExecuteRequest shall return the http status reported by the host in the received response. **]**
**SRS_HTTPAPI_COMPACT_21_047: [** The HTTPAPI_ExecuteRequest shall report the status in the statusCode parameter. **]**
**SRS_HTTPAPI_COMPACT_21_048: [** If the statusCode is NULL, the HTTPAPI_ExecuteRequest shall report not report any status. **]**
**SRS_HTTPAPI_COMPACT_21_049: [** If responseHeadersHandle is provide, the HTTPAPI_ExecuteRequest shall prepare a Response Header usign the HTTPHeaders_AddHeaderNameValuePair. **]**
**SRS_HTTPAPI_COMPACT_21_050: [** If there is a content in the response, the HTTPAPI_ExecuteRequest shall copy it in the responseContent buffer. **]**
**SRS_HTTPAPI_COMPACT_21_051: [** If the responseContent is NULL, the HTTPAPI_ExecuteRequest shall ignore any content in the response. **]**
**SRS_HTTPAPI_COMPACT_21_052: [** If any memory allocation get fail, the HTTPAPI_ExecuteRequest shall return HTTPAPI_ALLOC_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_053: [** The HTTPAPI_ExecuteRequest shall produce a set of http header to send to the host. **]**
**SRS_HTTPAPI_COMPACT_21_054: [** If Http header maker cannot provide the number of headers, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_055: [** If the HTTPAPI_ExecuteRequest cannot parser the recieved message, it shall return HTTPAPI_RECEIVE_RESPONSE_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_073: [** The message recieved by the HTTPAPI_ExecuteRequest shall starts with a valid header. **]**
**SRS_HTTPAPI_COMPACT_21_074: [** After the header, the message recieved by the HTTPAPI_ExecuteRequest can contain addition information about the content. **]**
**SRS_HTTPAPI_COMPACT_21_075: [** The message recieved by the HTTPAPI_ExecuteRequest can contain a body with the message content. **]**
**SRS_HTTPAPI_COMPACT_21_077: [** The HTTPAPI_ExecuteRequest shall wait, at least, 10 seconds for the SSL open process. **]**
**SRS_HTTPAPI_COMPACT_21_078: [** If the HTTPAPI_ExecuteRequest cannot open the connection in 10 seconds, it shall fail and return HTTPAPI_OPEN_REQUEST_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_079: [** The HTTPAPI_ExecuteRequest shall wait, at least, 20 seconds to send a buffer using the SSL connection. **]**
**SRS_HTTPAPI_COMPACT_21_080: [** If the HTTPAPI_ExecuteRequest retries to send the message for 20 seconds without success, it shall fail and return HTTPAPI_SEND_REQUEST_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_081: [** The HTTPAPI_ExecuteRequest shall try to read the message with the response up to 20 seconds. **]**
**SRS_HTTPAPI_COMPACT_21_082: [** If the HTTPAPI_ExecuteRequest retries 20 seconds to receive the message without success, it shall fail and return HTTPAPI_READ_DATA_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_021: [** The HTTPAPI_ExecuteRequest shall execute the http communtication with the provided host, sending a request and reciving the response. **]**
**SRS_HTTPAPI_COMPACT_21_022: [** If a Certificate was provided, the HTTPAPI_ExecuteRequest shall set this option on the transport layer. **]**
**SRS_HTTPAPI_COMPACT_21_023: [** If the transport failed setting the Certificate, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_SET_OPTION_FAILED. **]**
**SRS_HTTPAPI_COMPACT_06_003: [** If the x509 client certificate is provided, the HTTPAPI_ExecuteRequest shall set this option on the transport layer. **]**
**SRS_HTTPAPI_COMPACT_06_005: [** If the transport failed setting the client certificate, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_SET_OPTION_FAILED. **]**
**SRS_HTTPAPI_COMPACT_06_004: [** If the x509 client certificate private key is provided, the HTTPAPI_ExecuteRequest shall set this optionon the transport layer. **]**
**SRS_HTTPAPI_COMPACT_06_006: [** If the transport failed setting the client certificate private key, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_SET_OPTION_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_024: [** The HTTPAPI_ExecuteRequest shall open the transport connection with the host to send the request. **]**
**SRS_HTTPAPI_COMPACT_21_025: [** If the open process failed, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_OPEN_REQUEST_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_026: [** If the open process succeed, the HTTPAPI_ExecuteRequest shall send the request message to the host. **]**
**SRS_HTTPAPI_COMPACT_21_027: [** If the HTTPAPI_ExecuteRequest cannot create a buffer to send the request, it shall not send any request and return HTTPAPI_STRING_PROCESSING_ERROR. **]**
**SRS_HTTPAPI_COMPACT_21_028: [** If the HTTPAPI_ExecuteRequest cannot send the request header, it shall return HTTPAPI_HTTP_HEADERS_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_029: [** If the HTTPAPI_ExecuteRequest cannot send the buffer with the request, it shall return HTTPAPI_SEND_REQUEST_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_030: [** At the end of the transmission, the HTTPAPI_ExecuteRequest shall receive the response from the host. **]**
**SRS_HTTPAPI_COMPACT_21_032: [** If the HTTPAPI_ExecuteRequest cannot read the message with the request result, it shall return HTTPAPI_READ_DATA_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_033: [** If the whole process succeed, the HTTPAPI_ExecuteRequest shall retur HTTPAPI_OK. **]**
**SRS_HTTPAPI_COMPACT_21_034: [** If there is no previous connection, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_035: [** The HTTPAPI_ExecuteRequest shall execute resquest for types `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. **]**
**SRS_HTTPAPI_COMPACT_21_036: [** The request type shall be provided in the parameter requestType. **]**
**SRS_HTTPAPI_COMPACT_21_037: [** If the request type is unknown, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_038: [** The HTTPAPI_ExecuteRequest shall execute the resquest for the path in relativePath parameter. **]**
**SRS_HTTPAPI_COMPACT_21_039: [** If the relativePath is NULL or invalid, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_040: [** The request shall contain the http header provided in httpHeadersHandle parameter. **]**
**SRS_HTTPAPI_COMPACT_21_041: [** If the httpHeadersHandle is NULL or invalid, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_042: [** The request can contain the a content message, provided in content parameter. **]**
**SRS_HTTPAPI_COMPACT_21_043: [** If the content is NULL, the HTTPAPI_ExecuteRequest shall send the request without content. **]**
**SRS_HTTPAPI_COMPACT_21_044: [** If the content is not NULL, the number of bytes in the content shall be provided in contentLength parameter. **]**
**SRS_HTTPAPI_COMPACT_21_045: [** If the contentLength is lower than one, the HTTPAPI_ExecuteRequest shall send the request without content. **]**
**SRS_HTTPAPI_COMPACT_21_046: [** The HTTPAPI_ExecuteRequest shall return the http status reported by the host in the received response. **]**
**SRS_HTTPAPI_COMPACT_21_047: [** The HTTPAPI_ExecuteRequest shall report the status in the statusCode parameter. **]**
**SRS_HTTPAPI_COMPACT_21_048: [** If the statusCode is NULL, the HTTPAPI_ExecuteRequest shall report not report any status. **]**
**SRS_HTTPAPI_COMPACT_21_049: [** If responseHeadersHandle is provide, the HTTPAPI_ExecuteRequest shall prepare a Response Header usign the HTTPHeaders_AddHeaderNameValuePair. **]**
**SRS_HTTPAPI_COMPACT_21_050: [** If there is a content in the response, the HTTPAPI_ExecuteRequest shall copy it in the responseContent buffer. **]**
**SRS_HTTPAPI_COMPACT_21_051: [** If the responseContent is NULL, the HTTPAPI_ExecuteRequest shall ignore any content in the response. **]**
**SRS_HTTPAPI_COMPACT_21_052: [** If any memory allocation get fail, the HTTPAPI_ExecuteRequest shall return HTTPAPI_ALLOC_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_053: [** The HTTPAPI_ExecuteRequest shall produce a set of http header to send to the host. **]**
**SRS_HTTPAPI_COMPACT_21_054: [** If Http header maker cannot provide the number of headers, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_055: [** If the HTTPAPI_ExecuteRequest cannot parser the recieved message, it shall return HTTPAPI_RECEIVE_RESPONSE_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_073: [** The message recieved by the HTTPAPI_ExecuteRequest shall starts with a valid header. **]**
**SRS_HTTPAPI_COMPACT_21_074: [** After the header, the message recieved by the HTTPAPI_ExecuteRequest can contain addition information about the content. **]**
**SRS_HTTPAPI_COMPACT_21_075: [** The message recieved by the HTTPAPI_ExecuteRequest can contain a body with the message content. **]**
**SRS_HTTPAPI_COMPACT_21_077: [** The HTTPAPI_ExecuteRequest shall wait, at least, 10 seconds for the SSL open process. **]**
**SRS_HTTPAPI_COMPACT_21_078: [** If the HTTPAPI_ExecuteRequest cannot open the connection in 10 seconds, it shall fail and return HTTPAPI_OPEN_REQUEST_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_079: [** The HTTPAPI_ExecuteRequest shall wait, at least, 20 seconds to send a buffer using the SSL connection. **]**
**SRS_HTTPAPI_COMPACT_21_080: [** If the HTTPAPI_ExecuteRequest retries to send the message for 20 seconds without success, it shall fail and return HTTPAPI_SEND_REQUEST_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_081: [** The HTTPAPI_ExecuteRequest shall try to read the message with the response up to 20 seconds. **]**
**SRS_HTTPAPI_COMPACT_21_082: [** If the HTTPAPI_ExecuteRequest retries 20 seconds to receive the message without success, it shall fail and return HTTPAPI_READ_DATA_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_083: [** The HTTPAPI_ExecuteRequest shall wait, at least, 100 milliseconds between retries. **]**
### HTTPAPI_SetOption
### HTTPAPI_SetOption
```c
HTTPAPI_RESULT HTTPAPI_SetOption(HTTP_HANDLE handle, const char* optionName, const void* value);
```
**SRS_HTTPAPI_COMPACT_21_056: [** The HTTPAPI_SetOption shall change the HTTP options. **]**
**SRS_HTTPAPI_COMPACT_21_057: [** The HTTPAPI_SetOption shall recieve a handle that identiry the HTTP connection. **]**
**SRS_HTTPAPI_COMPACT_21_058: [** The HTTPAPI_SetOption shall recieve the option as a pair optionName/value. **]**
**SRS_HTTPAPI_COMPACT_21_059: [** If the handle is NULL, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_060: [** If the optionName is NULL, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_061: [** If the value is NULL, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_062: [** If any memory allocation get fail, the HTTPAPI_SetOption shall return HTTPAPI_ALLOC_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_063: [** If the HTTP do not support the optionName, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_056: [** The HTTPAPI_SetOption shall change the HTTP options. **]**
**SRS_HTTPAPI_COMPACT_21_057: [** The HTTPAPI_SetOption shall recieve a handle that identiry the HTTP connection. **]**
**SRS_HTTPAPI_COMPACT_21_058: [** The HTTPAPI_SetOption shall recieve the option as a pair optionName/value. **]**
**SRS_HTTPAPI_COMPACT_21_059: [** If the handle is NULL, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_060: [** If the optionName is NULL, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_061: [** If the value is NULL, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_062: [** If any memory allocation get fail, the HTTPAPI_SetOption shall return HTTPAPI_ALLOC_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_063: [** If the HTTP do not support the optionName, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_064: [** If the HTTPAPI_SetOption get success setting the option, it shall return HTTPAPI_OK. **]**
### HTTPAPI_CloneOption
### HTTPAPI_CloneOption
```c
HTTPAPI_RESULT HTTPAPI_CloneOption(const char* optionName, const void* value, const void** savedValue);
```
**SRS_HTTPAPI_COMPACT_21_065: [** The HTTPAPI_CloneOption shall provide the means to clone the HTTP option. **]**
**SRS_HTTPAPI_COMPACT_21_066: [** The HTTPAPI_CloneOption shall return a clone of the value identified by the optionName. **]**
**SRS_HTTPAPI_COMPACT_21_067: [** If the optionName is NULL, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_068: [** If the value is NULL, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_069: [** If the savedValue is NULL, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_070: [** If any memory allocation get fail, the HTTPAPI_CloneOption shall return HTTPAPI_ALLOC_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_071: [** If the HTTP do not support the optionName, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_065: [** The HTTPAPI_CloneOption shall provide the means to clone the HTTP option. **]**
**SRS_HTTPAPI_COMPACT_21_066: [** The HTTPAPI_CloneOption shall return a clone of the value identified by the optionName. **]**
**SRS_HTTPAPI_COMPACT_21_067: [** If the optionName is NULL, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_068: [** If the value is NULL, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_069: [** If the savedValue is NULL, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_070: [** If any memory allocation get fail, the HTTPAPI_CloneOption shall return HTTPAPI_ALLOC_FAILED. **]**
**SRS_HTTPAPI_COMPACT_21_071: [** If the HTTP do not support the optionName, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]**
**SRS_HTTPAPI_COMPACT_21_072: [** If the HTTPAPI_CloneOption get success setting the option, it shall return HTTPAPI_OK. **]**

159
devdoc/httpapiex_requirements.md
Просмотреть файл

@ -1,17 +1,17 @@
HTTPAPIEX Requirements
================
##Overview
## Overview
HTTAPIEX is a utility module that provides HTTP requests with build-in retry capability to an HTTP server. Features over "regular" HTTPAPI include:
- Optional parameters
- Implementation independent
- Retry mechanism
- Persistent options
##References
## References
[httpapi_requirements]
##Exposed API
## Exposed API
```c
#define HTTPAPIEX_RESULT_VALUES \
HTTPAPIEX_OK, \
@ -19,30 +19,34 @@ HTTAPIEX is a utility module that provides HTTP requests with build-in retry cap
HTTPAPIEX_INVALID_ARG, \
HTTPAPIEX_RECOVERYFAILED
/*to be continued*/
DEFINE_ENUM(HTTPAPIEX_RESULT, HTTPAPIEX_RESULT_VALUES);
extern HTTPAPIEX_HANDLE HTTPAPIEX_Create(const char* hostName);
extern HTTPAPIEX_RESULT HTTPAPIEX_ExecuteRequest(HTTPAPIEX_HANDLE handle, HTTPAPI_REQUEST_TYPE requestType, const char* relativePath, HTTP_HEADERS_HANDLE requestHttpHeadersHandle, BUFFER_HANDLE requestContent, unsigned int* statusCode, HTTP_HEADERS_HANDLE responseHeadersHandle, BUFFER_HANDLE responseContent);
extern void HTTPAPIEX_Destroy(HTTPAPIEX_HANDLE handle);
extern HTTPAPIEX_RESULT HTTPAPIEX_SetOption(HTTPAPIEX_HANDLE handle, const char* optionName, const void* value);
```
###HTTPAPIEX_Create
### HTTPAPIEX_Create
```c
HTTPAPIEX_HANDLE HTTPAPIEX_Create(const char* hostName)
```
HTTPAPIEX_Create shall create a HTTPAPIEX_HANDLE that can be used in further calls.
**SRS_HTTPAPIEX_02_001: [**If parameter hostName is NULL then HTTPAPIEX_Create shall return NULL.**]**
**SRS_HTTPAPIEX_02_002: [**Parameter hostName shall be saved.**]**
**SRS_HTTPAPIEX_02_003: [**If saving the parameter hostName fails for any reason, then HTTPAPIEX_Create shall return NULL.**]**
**SRS_HTTPAPIEX_02_004: [**Otherwise, HTTPAPIEX_Create shall return a HTTAPIEX_HANDLE suitable for further calls to the module.**]**
**SRS_HTTPAPIEX_02_005: [**If creating the handle fails for any reason, then HTTAPIEX_Create shall return NULL.**]**
###HTTPAPIEX_ExecuteRequest
HTTPAPIEX_Create shall create a HTTPAPIEX_HANDLE that can be used in further calls.
**SRS_HTTPAPIEX_02_001: [** If parameter hostName is NULL then HTTPAPIEX_Create shall return NULL. **]**
**SRS_HTTPAPIEX_02_002: [** Parameter hostName shall be saved. **]**
**SRS_HTTPAPIEX_02_003: [** If saving the parameter hostName fails for any reason, then HTTPAPIEX_Create shall return NULL. **]**
**SRS_HTTPAPIEX_02_004: [** Otherwise, HTTPAPIEX_Create shall return a HTTAPIEX_HANDLE suitable for further calls to the module. **]**
**SRS_HTTPAPIEX_02_005: [** If creating the handle fails for any reason, then HTTAPIEX_Create shall return NULL. **]**
### HTTPAPIEX_ExecuteRequest
```c
HTTPAPIEX_RESULT HTTPAPIEX_ExecuteRequest(HTTPAPIEX_HANDLE handle, HTTPAPI_REQUEST_TYPE requestType, const char* relativePath, HTTP_HEADERS_HANDLE requestHttpHeadersHandle, BUFFER_HANDLE requestContent, unsigned int* statusCode, HTTP_HEADERS_HANDLE responseHeadersHandle, BUFFER_HANDLE responseContent);
```
@ -50,66 +54,101 @@ HTTPAPIEX_RESULT HTTPAPIEX_ExecuteRequest(HTTPAPIEX_HANDLE handle, HTTPAPI_REQUE
HTTPAPIEX_ExecuteRequest tries to execute an HTTP request of type requestType, on the server's relativePath relativePath, pushing the request HTTP headers requestHttpHeadersHandle, having the content of the request as pointed to by requestcontent.
If successful, HTTAPIEX writes in the out parameter statusCode the HTTP status, populates the responseHeadersHandle with the response headers and copies the response body to responseContent.
**SRS_HTTPAPIEX_02_006: [**If parameter handle is NULL then HTTPAPIEX_ExecuteRequest shall fail and return HTTPAPIEX_INVALID_ARG.**]**
**SRS_HTTPAPIEX_02_007: [**If parameter requestType does not indicate a valid request, HTTPAPIEX_ExecuteRequest shall fail and return HTTPAPIEX_INVALID_ARG.**]**
**SRS_HTTPAPIEX_02_008: [**If parameter relativePath is NULL then HTTPAPIEX_INVALID_ARG shall not assume a relative path - that is, it will assume an empty path ("").**]**
**SRS_HTTPAPIEX_02_009: [**If parameter requestHttpHeadersHandle is NULL then HTTPAPIEX_ExecuteRequest shall allocate a temporary internal instance of HTTPHEADERS, shall add to that instance the following headers
**SRS_HTTPAPIEX_02_006: [** If parameter handle is NULL then HTTPAPIEX_ExecuteRequest shall fail and return HTTPAPIEX_INVALID_ARG. **]**
**SRS_HTTPAPIEX_02_007: [** If parameter requestType does not indicate a valid request, HTTPAPIEX_ExecuteRequest shall fail and return HTTPAPIEX_INVALID_ARG. **]**
**SRS_HTTPAPIEX_02_008: [** If parameter relativePath is NULL then HTTPAPIEX_INVALID_ARG shall not assume a relative path - that is, it will assume an empty path (""). **]**
**SRS_HTTPAPIEX_02_009: [** If parameter requestHttpHeadersHandle is NULL then HTTPAPIEX_ExecuteRequest shall allocate a temporary internal instance of HTTPHEADERS, shall add to that instance the following headers
Host:{hostname} - as it was indicated by the call to HTTPAPIEX_Create API call
Content-Length:the size of the requestContent parameter, and use this instance to all the subsequent calls to HTTPAPI_ExecuteRequest as parameter httpHeadersHandle.**]**
**SRS_HTTPAPIEX_02_010: [**If any of the operations in SRS_HTTAPIEX_02_009 fails, then HTTPAPIEX_ExecuteRequest shall return HTTPAPIEX_ERROR.**]**
**SRS_HTTPAPIEX_02_011: [**If parameter requestHttpHeadersHandle is not NULL then HTTPAPIEX_ExecuteRequest shall create or update the following headers of the request:
Content-Length:the size of the requestContent parameter, and use this instance to all the subsequent calls to HTTPAPI_ExecuteRequest as parameter httpHeadersHandle. **]**
**SRS_HTTPAPIEX_02_010: [** If any of the operations in SRS_HTTAPIEX_02_009 fails, then HTTPAPIEX_ExecuteRequest shall return HTTPAPIEX_ERROR. **]**
**SRS_HTTPAPIEX_02_011: [** If parameter requestHttpHeadersHandle is not NULL then HTTPAPIEX_ExecuteRequest shall create or update the following headers of the request:
Host:{hostname}
Content-Length:the size of the requestContent parameter, and shall use the so constructed HTTPHEADERS object to all calls to HTTPAPI_ExecuteRequest as parameter httpHeadersHandle.**]**
**SRS_HTTPAPIEX_02_012: [**If any of the operations required for SRS_HTTAPIEX_02_011 fails, then HTTPAPIEX_ExecuteRequest shall return HTTPAPIEX_ERROR.**]**
**SRS_HTTPAPIEX_02_013: [**If requestContent is NULL then HTTPAPIEX_ExecuteRequest shall behave as if a buffer of zero size would have been used, that is, it shall call HTTPAPI_ExecuteRequest with parameter content = NULL and contentLength = 0.**]**
**SRS_HTTPAPIEX_02_014: [**If requestContent is not NULL then its content and its size shall be used for parameters content and contentLength of HTTPAPI_ExecuteRequest.**]**
**SRS_HTTPAPIEX_02_015: [**If statusCode is NULL then HTTPAPIEX_ExecuteRequest shall not write in statusCode the HTTP status code, and it will use a temporary internal int for parameter statusCode to the calls of HTTPAPI_ExecuteRequest.**]**
**SRS_HTTPAPIEX_02_016: [**If statusCode is not NULL then If statusCode is NULL then HTTPAPIEX_ExecuteRequest shall use it for parameter statusCode to the calls of HTTPAPI_ExecuteRequest.**]**
**SRS_HTTPAPIEX_02_017: [**If responseHeaders handle is NULL then HTTPAPIEX_ExecuteRequest shall create a temporary internal instance of HTTPHEADERS object and use that for responseHeaders parameter of HTTPAPI_ExecuteRequest call.**]**
**SRS_HTTPAPIEX_02_018: [**If creating the temporary http headers in SRS_HTTPAPIEX_02_017 fails then HTTPAPIEX_ExecuteRequest shall return HTTPAPIEX_ERROR.**]**
**SRS_HTTPAPIEX_02_019: [**If responseHeaders is not NULL, then then HTTPAPIEX_ExecuteRequest shall use that object as parameter responseHeaders of HTTPAPI_ExecuteRequest call.**]**
**SRS_HTTPAPIEX_02_020: [**If responseContent is NULL then HTTPAPIEX_ExecuteRequest shall create a temporary internal BUFFER object and use that as parameter responseContent of HTTPAPI_ExecuteRequest call.**]**
**SRS_HTTPAPIEX_02_021: [**If creating the BUFFER_HANDLE in SRS_HTTPAPIEX_02_020 fails, then HTTPAPIEX_ExecuteRequest shall return HTTPAPIEX_ERROR.**]**
**SRS_HTTPAPIEX_02_022: [**If responseContent is not NULL then HTTPAPIEX_ExecuteRequest use that as parameter responseContent of HTTPAPI_ExecuteRequest call.**]**
**SRS_HTTPAPIEX_02_023: [**HTTPAPIEX_ExecuteRequest shall try to execute the HTTP call by ensuring the following API call sequence is respected:**]**
Content-Length:the size of the requestContent parameter, and shall use the so constructed HTTPHEADERS object to all calls to HTTPAPI_ExecuteRequest as parameter httpHeadersHandle. **]**
**SRS_HTTPAPIEX_02_012: [** If any of the operations required for SRS_HTTAPIEX_02_011 fails, then HTTPAPIEX_ExecuteRequest shall return HTTPAPIEX_ERROR. **]**
**SRS_HTTPAPIEX_02_013: [** If requestContent is NULL then HTTPAPIEX_ExecuteRequest shall behave as if a buffer of zero size would have been used, that is, it shall call HTTPAPI_ExecuteRequest with parameter content = NULL and contentLength = 0. **]**
**SRS_HTTPAPIEX_02_014: [** If requestContent is not NULL then its content and its size shall be used for parameters content and contentLength of HTTPAPI_ExecuteRequest. **]**
**SRS_HTTPAPIEX_02_015: [** If statusCode is NULL then HTTPAPIEX_ExecuteRequest shall not write in statusCode the HTTP status code, and it will use a temporary internal int for parameter statusCode to the calls of HTTPAPI_ExecuteRequest. **]**
**SRS_HTTPAPIEX_02_016: [** If statusCode is not NULL then If statusCode is NULL then HTTPAPIEX_ExecuteRequest shall use it for parameter statusCode to the calls of HTTPAPI_ExecuteRequest. **]**
**SRS_HTTPAPIEX_02_017: [** If responseHeaders handle is NULL then HTTPAPIEX_ExecuteRequest shall create a temporary internal instance of HTTPHEADERS object and use that for responseHeaders parameter of HTTPAPI_ExecuteRequest call. **]**
**SRS_HTTPAPIEX_02_018: [** If creating the temporary http headers in SRS_HTTPAPIEX_02_017 fails then HTTPAPIEX_ExecuteRequest shall return HTTPAPIEX_ERROR. **]**
**SRS_HTTPAPIEX_02_019: [** If responseHeaders is not NULL, then then HTTPAPIEX_ExecuteRequest shall use that object as parameter responseHeaders of HTTPAPI_ExecuteRequest call. **]**
**SRS_HTTPAPIEX_02_020: [** If responseContent is NULL then HTTPAPIEX_ExecuteRequest shall create a temporary internal BUFFER object and use that as parameter responseContent of HTTPAPI_ExecuteRequest call. **]**
**SRS_HTTPAPIEX_02_021: [** If creating the BUFFER_HANDLE in SRS_HTTPAPIEX_02_020 fails, then HTTPAPIEX_ExecuteRequest shall return HTTPAPIEX_ERROR. **]**
**SRS_HTTPAPIEX_02_022: [** If responseContent is not NULL then HTTPAPIEX_ExecuteRequest use that as parameter responseContent of HTTPAPI_ExecuteRequest call. **]**
**SRS_HTTPAPIEX_02_023: [** HTTPAPIEX_ExecuteRequest shall try to execute the HTTP call by ensuring the following API call sequence is respected: **]**
1. HTTPAPI_Init
2. HTTPAPI_CreateConnection
3. HTTPAPI_ExecuteRequest
**SRS_HTTPAPIEX_02_035: [**HTTPAPIEX_ExecuteRequest shall pass all the saved options (see HTTPAPIEX_SetOption) to the newly create HTTPAPI_HANDLE in step 2 by calling HTTPAPI_SetOption.**]**
**SRS_HTTPAPIEX_02_036: [**If setting the option fails, then the failure shall be ignored.**]**
**SRS_HTTPAPIEX_02_024: [**If any point in the sequence fails, HTTPAPIEX_ExecuteRequest shall attempt to recover by going back to the previous step and retrying that step.**]**
**SRS_HTTPAPIEX_02_025: [**If the first step fails, then the sequence fails.**]**
**SRS_HTTPAPIEX_02_026: [**A step shall be retried at most once.**]**
**SRS_HTTPAPIEX_02_027: [**If a step has been retried then all subsequent steps shall be retried too.**]**
**SRS_HTTPAPIEX_02_028: [**HTTPAPIEX_ExecuteRequest shall return HTTPAPIEX_OK when a call to HTTPAPI_ExecuteRequest has been completed successfully.**]**
**SRS_HTTPAPIEX_02_029: [**Otherwise, HTTAPIEX_ExecuteRequest shall return HTTPAPIEX_RECOVERYFAILED.**]**
**SRS_HTTPAPIEX_02_035: [** HTTPAPIEX_ExecuteRequest shall pass all the saved options (see HTTPAPIEX_SetOption) to the newly create HTTPAPI_HANDLE in step 2 by calling HTTPAPI_SetOption. **]**
###HTTPAPIEX_Destroy
**SRS_HTTPAPIEX_02_036: [** If setting the option fails, then the failure shall be ignored. **]**
**SRS_HTTPAPIEX_02_024: [** If any point in the sequence fails, HTTPAPIEX_ExecuteRequest shall attempt to recover by going back to the previous step and retrying that step. **]**
**SRS_HTTPAPIEX_02_025: [** If the first step fails, then the sequence fails. **]**
**SRS_HTTPAPIEX_02_026: [** A step shall be retried at most once. **]**
**SRS_HTTPAPIEX_02_027: [** If a step has been retried then all subsequent steps shall be retried too. **]**
**SRS_HTTPAPIEX_02_028: [** HTTPAPIEX_ExecuteRequest shall return HTTPAPIEX_OK when a call to HTTPAPI_ExecuteRequest has been completed successfully. **]**
**SRS_HTTPAPIEX_02_029: [** Otherwise, HTTAPIEX_ExecuteRequest shall return HTTPAPIEX_RECOVERYFAILED. **]**
### HTTPAPIEX_Destroy
```c
void HTTPAPIEX_Destroy(HTTPAPIEX_HANDLE handle);
```
**SRS_HTTPAPIEX_02_043: [**If parameter handle is NULL then HTTPAPIEX_Destroy shall take no action.**]**
**SRS_HTTPAPIEX_02_042: [**HTTPAPIEX_Destroy shall free all the resources used by HTTAPIEX_HANDLE.**]**
**SRS_HTTPAPIEX_02_043: [** If parameter handle is NULL then HTTPAPIEX_Destroy shall take no action. **]**
###HTTPAPIEX_SetOption
**SRS_HTTPAPIEX_02_042: [** HTTPAPIEX_Destroy shall free all the resources used by HTTAPIEX_HANDLE. **]**
### HTTPAPIEX_SetOption
```c
extern HTTPAPIEX_RESULT HTTPAPIEX_SetOption(HTTPAPIEX_HANDLE handle, const char* optionName, const void* value);
```
HTTPAPIEX_SetOption set the option "optionName" to the value pointed to by value. Since underlying layer's handle is not necessarily created yet at the time of HTTPAPIEX_SetOption, the options and values are to be saved until the HTTPAPI_HANDLE is created and passed to HTTPAPI_HANDLE at that time. If HTTPAPI_HANDLE exists at the time of calling HTTPAPIEX_SetOption, the option and the value are still saved and passed immediately to HTTPAPI_SetOption.
**SRS_HTTPAPIEX_02_032: [**If parameter handle is NULL then HTTPAPIEX_SetOption shall return HTTPAPIEX_INVALID_ARG.**]**
**SRS_HTTPAPIEX_02_033: [**If parameter optionName is NULL then HTTPAPIEX_SetOption shall return HTTPAPIEX_INVALID_ARG.**]**
**SRS_HTTPAPIEX_02_034: [**If parameter value is NULL then HTTPAPIEX_SetOption shall return HTTPAPIEX_INVALID_ARG.**]**
**SRS_HTTPAPIEX_02_030: [**If parameter optionName is one of the options handled by HTTPAPIEX then it shall be set to value *value.**]**
**SRS_HTTPAPIEX_02_037: [**HTTPAPIEX_SetOption shall attempt to save the value of the option by calling HTTPAPI_CloneOption passing optionName and value, irrespective of the existence of a HTTPAPI_HANDLE**]**
**SRS_HTTPAPIEX_02_038: [**If HTTPAPI_CloneOption returns HTTPAPI_INVALID_ARG then HTTPAPIEX shall return HTTPAPIEX_INVALID_ARG.**]**
**SRS_HTTPAPIEX_02_039: [**If HTTPAPI_CloneOption returns HTTPAPI_OK then HTTPAPIEX_SetOption shall create or update the pair optionName/value.**]**
**SRS_HTTPAPIEX_02_041: [**If creating or updating the pair optionName/value fails then shall return HTTPAPIEX_ERROR.**]**
**SRS_HTTPAPIEX_02_040: [**For all other return values of HTTPAPI_SetOption, HTTPIAPIEX_SetOption shall return HTTPAPIEX_ERROR.**]**
**SRS_HTTPAPIEX_02_031: [**If HTTPAPI_HANDLE exists then HTTPAPIEX_SetOption shall call HTTPAPI_SetOption passing the same optionName and value and shall return a value conforming to the below table:**]**
**SRS_HTTPAPIEX_02_032: [** If parameter handle is NULL then HTTPAPIEX_SetOption shall return HTTPAPIEX_INVALID_ARG. **]**
**SRS_HTTPAPIEX_02_033: [** If parameter optionName is NULL then HTTPAPIEX_SetOption shall return HTTPAPIEX_INVALID_ARG. **]**
**SRS_HTTPAPIEX_02_034: [** If parameter value is NULL then HTTPAPIEX_SetOption shall return HTTPAPIEX_INVALID_ARG. **]**
**SRS_HTTPAPIEX_02_030: [** If parameter optionName is one of the options handled by HTTPAPIEX then it shall be set to value *value. **]**
**SRS_HTTPAPIEX_02_037: [** HTTPAPIEX_SetOption shall attempt to save the value of the option by calling HTTPAPI_CloneOption passing optionName and value, irrespective of the existence of a HTTPAPI_HANDLE **]**
**SRS_HTTPAPIEX_02_038: [** If HTTPAPI_CloneOption returns HTTPAPI_INVALID_ARG then HTTPAPIEX shall return HTTPAPIEX_INVALID_ARG. **]**
**SRS_HTTPAPIEX_02_039: [** If HTTPAPI_CloneOption returns HTTPAPI_OK then HTTPAPIEX_SetOption shall create or update the pair optionName/value. **]**
**SRS_HTTPAPIEX_02_041: [** If creating or updating the pair optionName/value fails then shall return HTTPAPIEX_ERROR. **]**
**SRS_HTTPAPIEX_02_040: [** For all other return values of HTTPAPI_SetOption, HTTPIAPIEX_SetOption shall return HTTPAPIEX_ERROR. **]**
**SRS_HTTPAPIEX_02_031: [** If HTTPAPI_HANDLE exists then HTTPAPIEX_SetOption shall call HTTPAPI_SetOption passing the same optionName and value and shall return a value conforming to the below table: **]**
|HTTPAPI return code |HTTPAPIEX return code|
|-------------------------------|---------------------|
|HTTPAPI_OK |HTTPAPIEX_OK |

76
devdoc/httpapiexsas_requirements.md
Просмотреть файл

@ -1,21 +1,21 @@
HTTPAPIEX SAS Requirements
================
##Overview
## Overview
This module is used to manage the SAS Tokens within HTTP headers that are passing through to the HTTPAPIEX interface.
A guiding principle of this module to that if SAS Tokens are being used within the http headers then at all costs SAS token expiration should be avoided.
Retransmission is very expensive. Additionally this module does not try to enforce any policy on the headers.
For instance, if there is no "Authorization" header, this module will make no attempt to error out. It will still try to invoke the HTTPAPIEX_ExecuteRequest.
##References
## References
[SAS Token Create requirements]
[HTTPAPIEX requirements]
[HTTP headers requirements]
##Exposed API
## Exposed API
```c
typedef void* HTTPAPIEX_SAS_HANDLE;
@ -25,44 +25,64 @@ extern void HTTPAPIEX_SAS_Destroy(HTTPAPIEX_SAS_HANDLE handle);
extern HTTPAPIEX_RESULT HTTPAPIEX_SAS_ExecuteRequest(HTTPAPIEX_SAS_HANDLE sasHandle, HTTPAPIEX_HANDLE handle, HTTPAPI_REQUEST_TYPE requestType, const char* relativePath, HTTP_HEADERS_HANDLE requestHttpHeadersHandle, BUFFER_HANDLE requestContent, unsigned int* statusCode, HTTP_HEADERS_HANDLE responseHeadersHandle, BUFFER_HANDLE responseContent);
```
###HTTPAPIEX_SAS_Create
### HTTPAPIEX_SAS_Create
```c
extern HTTPAPIEX_SAS_HANDLE HTTPAPIEX_SAS_Create(STRING_HANDLE key, STRING_HANDLE uriResource, STRING_HANDLE keyName);
```
**SRS_HTTPAPIEXSAS_01_001: [** HTTPAPIEX_SAS_Create shall create a new instance of HTTPAPIEX_SAS and return a non-NULL handle to it. **]**
**SRS_HTTPAPIEXSAS_06_001: [**If the parameter key is NULL then HTTPAPIEX_SAS_Create shall return NULL.**]**
**SRS_HTTPAPIEXSAS_06_002: [**If the parameter uriResource is NULL then HTTPAPIEX_SAS_Create shall return NULL.**]**
**SRS_HTTPAPIEXSAS_06_003: [**If the parameter keyName is NULL then HTTPAPIEX_SAS_Create shall return NULL.**]**
**SRS_HTTPAPIEXSAS_06_004: [**If there are any other errors in the instantiation of this handle then HTTPAPIEX_SAS_Create shall return NULL.**]**
###HTTPAPIEX_SAS_Destroy
**SRS_HTTPAPIEXSAS_06_001: [** If the parameter key is NULL then HTTPAPIEX_SAS_Create shall return NULL. **]**
**SRS_HTTPAPIEXSAS_06_002: [** If the parameter uriResource is NULL then HTTPAPIEX_SAS_Create shall return NULL. **]**
**SRS_HTTPAPIEXSAS_06_003: [** If the parameter keyName is NULL then HTTPAPIEX_SAS_Create shall return NULL. **]**
**SRS_HTTPAPIEXSAS_06_004: [** If there are any other errors in the instantiation of this handle then HTTPAPIEX_SAS_Create shall return NULL. **]**
### HTTPAPIEX_SAS_Destroy
```c
extern void HTTPAPIEX_SAS_Destroy(HTTPAPIEX_SAS_HANDLE handle);
```
**SRS_HTTPAPIEXSAS_06_005: [**If the parameter handle is NULL then HTTAPIEX_SAS_Destroy shall do nothing and return.**]**
Otherwise, **SRS_HTTPAPIEXSAS_06_006: [**HTTAPIEX_SAS_Destroy shall deallocate any structures denoted by the parameter handle.**]**
###HTTPAPIEX_SAS_ExecuteRequest
**SRS_HTTPAPIEXSAS_06_005: [** If the parameter handle is NULL then HTTAPIEX_SAS_Destroy shall do nothing and return. **]**
Otherwise, **SRS_HTTPAPIEXSAS_06_006: [** HTTAPIEX_SAS_Destroy shall deallocate any structures denoted by the parameter handle. **]**
### HTTPAPIEX_SAS_ExecuteRequest
```c
extern HTTPAPIEX_RESULT HTTPAPIEX_SAS_ExecuteRequest(HTTPAPIEX_SAS_HANDLE sasHandle, HTTPAPIEX_HANDLE handle, HTTPAPI_REQUEST_TYPE requestType, const char* relativePath, HTTP_HEADERS_HANDLE requestHttpHeadersHandle, BUFFER_HANDLE requestContent, unsigned int* statusCode, HTTP_HEADERS_HANDLE responseHeadersHandle, BUFFER_HANDLE responseContent);
```
**SRS_HTTPAPIEXSAS_06_007: [**If the parameter sasHandle is NULL then HTTPAPIEX_SAS_ExecuteRequest shall simply invoke HTTPAPIEX_ExecuteRequest with the remaining parameters (following sasHandle) as its arguments and shall return immediately with the result of that call as the result of HTTPAPIEX_SAS_ExecuteRequest.**]**
**SRS_HTTPAPIEXSAS_06_007: [** If the parameter sasHandle is NULL then HTTPAPIEX_SAS_ExecuteRequest shall simply invoke HTTPAPIEX_ExecuteRequest with the remaining parameters (following sasHandle) as its arguments and shall return immediately with the result of that call as the result of HTTPAPIEX_SAS_ExecuteRequest. **]**
This invocation of HTTPAPIEX_ExecuteRequest and returning its result as the result of HTTPAPIEX_SAS_ExecuteRequest shall be henceforth known as fallthrough.
Otherwise,**SRS_HTTPAPIEXSAS_06_008: [**if the parameter requestHttpHeadersHandle is NULL then fallthrough.**]**
**SRS_HTTPAPIEXSAS_06_009: [**HTTPHeaders_FindHeaderValue shall be invoked with the requestHttpHeadersHandle as its first argument and the string "Authorization" as its second argument.**]**
**SRS_HTTPAPIEXSAS_06_010: [**If the return result of the invocation of HTTPHeaders_FindHeaderValue is NULL then fallthrough.**]**
Otherwise,**SRS_HTTPAPIEXSAS_06_008: [** if the parameter requestHttpHeadersHandle is NULL then fallthrough. **]**
**SRS_HTTPAPIEXSAS_06_009: [** HTTPHeaders_FindHeaderValue shall be invoked with the requestHttpHeadersHandle as its first argument and the string "Authorization" as its second argument. **]**
**SRS_HTTPAPIEXSAS_06_010: [** If the return result of the invocation of HTTPHeaders_FindHeaderValue is NULL then fallthrough. **]**
The caller of HTTPAPIEX_SAS_ExecuteRequest may know that there is no "Authorization" header. HTTPAPIEX_SAS_ExecuteRequest does not try to enforce policy.
**SRS_HTTPAPIEXSAS_06_018: [**A value of type time_t that shall be known as currentTime is obtained from calling get_time.**]**
**SRS_HTTPAPIEXSAS_06_019: [**If the value of currentTime is (time_t)-1 is then fallthrough.**]** The size_t value ((size_t) (difftime(currentTime,0) + 3600)) is obtained an shall be known as expiry. **SRS_HTTPAPIEXSAS_06_011: [**SASToken_Create shall be invoked.**]** **SRS_HTTPAPIEXSAS_06_012: [**If the return result of SASToken_Create is NULL then fallthrough.**]**
**SRS_HTTPAPIEXSAS_06_018: [** A value of type time_t that shall be known as currentTime is obtained from calling get_time. **]**
**SRS_HTTPAPIEXSAS_06_019: [** If the value of currentTime is (time_t)-1 is then fallthrough. **]**
The size_t value ((size_t) (difftime(currentTime,0) + 3600)) is obtained an shall be known as expiry.
**SRS_HTTPAPIEXSAS_06_011: [** SASToken_Create shall be invoked. **]**
**SRS_HTTPAPIEXSAS_06_012: [** If the return result of SASToken_Create is NULL then fallthrough. **]**
The call to HTTPAPIEX_ExecuteRequest is attempted because there certainly could still be a valid SAS Token as the value the Authorization header. Note also that an error will be logged that the token could not be created.
The result of the SASToken_Create shall be known as newSASToken.
**SRS_HTTPAPIEXSAS_06_013: [**HTTPHeaders_ReplaceHeaderNameValuePair shall be invoked with "Authorization" as its second argument and STRING_c_str (newSASToken) as its third argument.**]**
**SRS_HTTPAPIEXSAS_06_015: [**STRING_delete(newSASToken) will be invoked.**]**
**SRS_HTTPAPIEXSAS_06_014: [**If the result of the invocation of HTTPHeaders_ReplaceHeaderNameValuePair is NOT HTTP_HEADERS_OK then fallthrough.**]**
Note that an error will be logged that the "Authorization" header could not be replaced.
Finally, **SRS_HTTPAPIEXSAS_06_016: [**HTTPAPIEX_ExecuteRequest with the remaining parameters (following sasHandle) as its arguments will be invoked and the result of that call is the result of HTTPAPIEX_SAS_ExecuteRequest.**]**
**SRS_HTTPAPIEXSAS_06_013: [** HTTPHeaders_ReplaceHeaderNameValuePair shall be invoked with "Authorization" as its second argument and STRING_c_str (newSASToken) as its third argument. **]**
**SRS_HTTPAPIEXSAS_06_015: [** STRING_delete(newSASToken) will be invoked. **]**
**SRS_HTTPAPIEXSAS_06_014: [** If the result of the invocation of HTTPHeaders_ReplaceHeaderNameValuePair is NOT HTTP_HEADERS_OK then fallthrough. **]**
Note that an error will be logged that the "Authorization" header could not be replaced.
Finally, **SRS_HTTPAPIEXSAS_06_016: [** HTTPAPIEX_ExecuteRequest with the remaining parameters (following sasHandle) as its arguments will be invoked and the result of that call is the result of HTTPAPIEX_SAS_ExecuteRequest. **]**

144
devdoc/httpheaders_requirements.md
Просмотреть файл

@ -1,16 +1,16 @@
httpheaders requirements
================
##Overview
## Overview
HttpHeaders is a utility module that handles message-headers. HttpHeaders uses Map function calls to store / retrieve http headers.
##References
[http headers: http://tools.ietf.org/html/rfc2616 , section 4.2, section 4.1](http://tools.ietf.org/html/rfc2616)
[structure of header fields: http://tools.ietf.org/html/rfc822#section-3.1](http://tools.ietf.org/html/rfc822#section-3.1)
## References
[http headers: http://tools.ietf.org/html/rfc2616 , section 4.2, section 4.1](http://tools.ietf.org/html/rfc2616)
[structure of header fields: http://tools.ietf.org/html/rfc822#section-3.1](http://tools.ietf.org/html/rfc822#section-3.1)
##Exposed API
**SRS_HTTP_HEADERS_99_001: [** HttpHeaders shall have the following interface**]**
## Exposed API
**SRS_HTTP_HEADERS_99_001: [** HttpHeaders shall have the following interface **]**
```c
typedef enum HTTP_HEADERS_RESULT_TAG
{
@ -20,9 +20,9 @@ typedef enum HTTP_HEADERS_RESULT_TAG
HTTP_HEADERS_INSUFFICIENT_BUFFER,
HTTP_HEADERS_ERROR
} HTTP_HEADERS_RESULT;
typedef void* HTTP_HEADERS_HANDLE;
extern HTTP_HEADERS_HANDLE HTTPHeaders_Alloc(void);
extern void HTTPHeaders_Free(HTTP_HEADERS_HANDLE httpHeadersHandle);
extern HTTP_HEADERS_RESULT HTTPHeaders_AddHeaderNameValuePair(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name, const char* value);
@ -39,83 +39,109 @@ HTTPHeaders_FindHeaderValue - when the name of the header is known and it wants
HTTPHeaders_GetHeaderCount - when the application needs to know the count of all the headers
HTTPHeaders_GetHeader - when the application needs to know the retrieve name+": "+value based on an index.
###HTTPHeaders_Alloc
### HTTPHeaders_Alloc
```c
HTTP_HEADERS_HANDLE HTTPHeaders_Alloc(void);
```
**SRS_HTTP_HEADERS_99_002: [** This API shall produce a HTTP_HANDLE that can later be used in subsequent calls to the module.**]**
**SRS_HTTP_HEADERS_99_003: [** The function shall return NULL when the function cannot execute properly**]**
**SRS_HTTP_HEADERS_99_004: [** After a successful init, HTTPHeaders_GetHeaderCount shall report 0 existing headers.**]**
**SRS_HTTP_HEADERS_99_002: [** This API shall produce a HTTP_HANDLE that can later be used in subsequent calls to the module. **]**
###HTTPHeaders_Free
**SRS_HTTP_HEADERS_99_003: [** The function shall return NULL when the function cannot execute properly **]**
**SRS_HTTP_HEADERS_99_004: [** After a successful init, HTTPHeaders_GetHeaderCount shall report 0 existing headers. **]**
### HTTPHeaders_Free
```c
HTTPHeaders_Free(HTTP_HEADERS_HANDLE httpHeadersHandle)
HTTPHeaders_Free(HTTP_HEADERS_HANDLE httpHeadersHandle);
```
**SRS_HTTP_HEADERS_99_005: [** Calling this API shall de-allocate the data structures allocated by previous API calls to the same handle.**]**
**SRS_HTTP_HEADERS_02_001: [**If httpHeadersHandle is NULL then HTTPHeaders_Free shall perform no action.**]**
###HTTPHeaders_AddHeaderNameValuePair
**SRS_HTTP_HEADERS_99_005: [** Calling this API shall de-allocate the data structures allocated by previous API calls to the same handle. **]**
**SRS_HTTP_HEADERS_02_001: [** If httpHeadersHandle is NULL then HTTPHeaders_Free shall perform no action. **]**
### HTTPHeaders_AddHeaderNameValuePair
```c
HTTP_HEADERS_RESULT HTTPHeaders_AddHeaderNameValuePair(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name, const char* value)
HTTP_HEADERS_RESULT HTTPHeaders_AddHeaderNameValuePair(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name, const char* value);
```
**SRS_HTTP_HEADERS_99_012: [** Calling this API shall record a header from name and value parameters.**]**
**SRS_HTTP_HEADERS_99_013: [** The function shall return HTTP_HEADERS_OK when execution is successful.**]**
**SRS_HTTP_HEADERS_99_014: [** The function shall return when the handle is not valid or when name parameter is NULL or when value parameter is NULL.**]**
**SRS_HTTP_HEADERS_99_015: [** The function shall return HTTP_HEADERS_ALLOC_FAILED when an internal request to allocate memory fails.**]**
**SRS_HTTP_HEADERS_99_016: [** The function shall store the name:value pair in such a way that when later retrieved by a call to GetHeader it will return a string that shall strcmp equal to the name+": "+value.**]**
**SRS_HTTP_HEADERS_99_017: [** If the name already exists in the collection of headers, the function shall concatenate the new value after the existing value, separated by a comma and a space as in: old-value+", "+new-value.**]**
**SRS_HTTP_HEADERS_99_031: [** If name contains the character ":" then the return value shall be HTTP_HEADERS_INVALID_ARG.**]**
**SRS_HTTP_HEADERS_99_036: [** If name contains the characters outside character codes 33 to 126 then the return value shall be HTTP_HEADERS_INVALID_ARG**]** (so says http://tools.ietf.org/html/rfc822#section-3.1)
**SRS_HTTP_HEADERS_02_002: [**The LWS from the beginning of the value shall not be stored.**]**
###HTTPHeaders_ReplaceHeaderNameValuePair
**SRS_HTTP_HEADERS_99_012: [** Calling this API shall record a header from name and value parameters. **]**
**SRS_HTTP_HEADERS_99_013: [** The function shall return HTTP_HEADERS_OK when execution is successful. **]**
**SRS_HTTP_HEADERS_99_014: [** The function shall return when the handle is not valid or when name parameter is NULL or when value parameter is NULL. **]**
**SRS_HTTP_HEADERS_99_015: [** The function shall return HTTP_HEADERS_ALLOC_FAILED when an internal request to allocate memory fails. **]**
**SRS_HTTP_HEADERS_99_016: [** The function shall store the name:value pair in such a way that when later retrieved by a call to GetHeader it will return a string that shall strcmp equal to the name+": "+value. **]**
**SRS_HTTP_HEADERS_99_017: [** If the name already exists in the collection of headers, the function shall concatenate the new value after the existing value, separated by a comma and a space as in: old-value+", "+new-value. **]**
**SRS_HTTP_HEADERS_99_031: [** If name contains the character ":" then the return value shall be HTTP_HEADERS_INVALID_ARG. **]**
**SRS_HTTP_HEADERS_99_036: [** If name contains the characters outside character codes 33 to 126 then the return value shall be HTTP_HEADERS_INVALID_ARG **]** (so says http://tools.ietf.org/html/rfc822#section-3.1)
**SRS_HTTP_HEADERS_02_002: [** The LWS from the beginning of the value shall not be stored. **]**
### HTTPHeaders_ReplaceHeaderNameValuePair
```c
HTTP_HEADERS_RESULT HTTPHeaders_ReplaceHeaderNameValuePair(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name, const char* value)
HTTP_HEADERS_RESULT HTTPHeaders_ReplaceHeaderNameValuePair(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name, const char* value);
```
**SRS_HTTP_HEADERS_06_001: [**This API will perform exactly as HTTPHeaders_AddHeaderNameValuePair except that if the header name already exists the already existing value will be replaced as opposed to concatenated to.**]**
###HTTPHeaders_FindHeaderValue
**SRS_HTTP_HEADERS_06_001: [** This API will perform exactly as HTTPHeaders_AddHeaderNameValuePair except that if the header name already exists the already existing value will be replaced as opposed to concatenated to. **]**
### HTTPHeaders_FindHeaderValue
```c
const char* HTTPHeaders_FindHeaderValue(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name)
const char* HTTPHeaders_FindHeaderValue(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name);
```
**SRS_HTTP_HEADERS_99_018: [** Calling this API shall retrieve the value for a previously stored name.**]**
**SRS_HTTP_HEADERS_99_022: [** The return value shall be NULL if name parameter is NULL or if httpHeadersHandle is NULL**]**
**SRS_HTTP_HEADERS_99_020: [** The return value shall be different than NULL when the name matches the name of a previously stored name:value pair.**]**
**SRS_HTTP_HEADERS_99_021: [** In this case the return value shall point to a string that shall strcmp equal to the original stored string.**]**
**SRS_HTTP_HEADERS_99_018: [** Calling this API shall retrieve the value for a previously stored name. **]**
###HTTPHeaders_GetHeaderCount
**SRS_HTTP_HEADERS_99_022: [** The return value shall be NULL if name parameter is NULL or if httpHeadersHandle is NULL **]**
**SRS_HTTP_HEADERS_99_020: [** The return value shall be different than NULL when the name matches the name of a previously stored name:value pair. **]**
**SRS_HTTP_HEADERS_99_021: [** In this case the return value shall point to a string that shall strcmp equal to the original stored string. **]**
### HTTPHeaders_GetHeaderCount
```c
HTTP_HEADERS_RESULT HTTPHeaders_GetHeaderCount(HTTP_HEADERS_HANDLE httpHeadersHandle, size_t* headersCount)
HTTP_HEADERS_RESULT HTTPHeaders_GetHeaderCount(HTTP_HEADERS_HANDLE httpHeadersHandle, size_t* headersCount);
```
**SRS_HTTP_HEADERS_99_023: [** Calling this API shall provide the number of stored headers.**]**
**SRS_HTTP_HEADERS_99_024: [** The function shall return HTTP_HEADERS_INVALID_ARG when an invalid handle is passed.**]**
**SRS_HTTP_HEADERS_99_025: [** The function shall return HTTP_HEADERS_INVALID_ARG when headersCount is NULL.**]**
**SRS_HTTP_HEADERS_99_026: [** The function shall write in *headersCount the number of currently stored headers and shall return HTTP_HEADERS_OK**]**
**SRS_HTTP_HEADERS_99_037: [** The function shall return HTTP_HEADERS_ERROR when an internal error occurs.**]**
**SRS_HTTP_HEADERS_99_023: [** Calling this API shall provide the number of stored headers. **]**
###HTTPHeaders_GetHeader
**SRS_HTTP_HEADERS_99_024: [** The function shall return HTTP_HEADERS_INVALID_ARG when an invalid handle is passed. **]**
**SRS_HTTP_HEADERS_99_025: [** The function shall return HTTP_HEADERS_INVALID_ARG when headersCount is NULL. **]**
**SRS_HTTP_HEADERS_99_026: [** The function shall write in *headersCount the number of currently stored headers and shall return HTTP_HEADERS_OK **]**
**SRS_HTTP_HEADERS_99_037: [** The function shall return HTTP_HEADERS_ERROR when an internal error occurs. **]**
### HTTPHeaders_GetHeader
```c
HTTP_HEADERS_RESULT HTTPHeaders_GetHeader(HTTP_HEADERS_HANDLE handle, size_t index, char** destination);
```
**SRS_HTTP_HEADERS_99_027: [** Calling this API shall produce the string value+": "+pair) for the index header in the *destination parameter.**]**
**SRS_HTTP_HEADERS_99_028: [** The function shall return HTTP_HEADERS_INVALID_ARG if the handle is invalid.**]**
**SRS_HTTP_HEADERS_99_029: [** The function shall return HTTP_HEADERS_INVALID_ARG if index is not valid (for example, out of range) for the currently stored headers.**]**
**SRS_HTTP_HEADERS_99_032: [** The function shall return HTTP_HEADERS_INVALID_ARG if the destination is NULL**]**
**SRS_HTTP_HEADERS_99_034: [** The function shall return HTTP_HEADERS_ERROR when an internal error occurs**]**
**SRS_HTTP_HEADERS_99_035: [** The function shall return HTTP_HEADERS_OK when the function executed without error.**]**
**SRS_HTTP_HEADERS_99_027: [** Calling this API shall produce the string value+": "+pair) for the index header in the *destination parameter. **]**
###HTTPHeaders_Clone
**SRS_HTTP_HEADERS_99_028: [** The function shall return HTTP_HEADERS_INVALID_ARG if the handle is invalid. **]**
**SRS_HTTP_HEADERS_99_029: [** The function shall return HTTP_HEADERS_INVALID_ARG if index is not valid (for example, out of range) for the currently stored headers. **]**
**SRS_HTTP_HEADERS_99_032: [** The function shall return HTTP_HEADERS_INVALID_ARG if the destination is NULL **]**
**SRS_HTTP_HEADERS_99_034: [** The function shall return HTTP_HEADERS_ERROR when an internal error occurs **]**
**SRS_HTTP_HEADERS_99_035: [** The function shall return HTTP_HEADERS_OK when the function executed without error. **]**
### HTTPHeaders_Clone
```c
extern HTTP_HEADERS_HANDLE HTTPHeaders_Clone(HTTP_HEADERS_HANDLE handle);
```
HTTPHeaders_Clone produces a clone of the handle parameter.
**SRS_HTTP_HEADERS_02_003: [**If handle is NULL then HTTPHeaders_Clone shall return NULL.**]**
**SRS_HTTP_HEADERS_02_004: [**Otherwise HTTPHeaders_Clone shall clone the content of handle to a new handle.**]**
**SRS_HTTP_HEADERS_02_005: [**If cloning fails for any reason, then HTTPHeaders_Clone shall return NULL.**]**
**SRS_HTTP_HEADERS_02_003: [** If handle is NULL then HTTPHeaders_Clone shall return NULL. **]**
**SRS_HTTP_HEADERS_02_004: [** Otherwise HTTPHeaders_Clone shall clone the content of handle to a new handle. **]**
**SRS_HTTP_HEADERS_02_005: [** If cloning fails for any reason, then HTTPHeaders_Clone shall return NULL. **]**

188
devdoc/map_requirements.md
Просмотреть файл

@ -1,16 +1,16 @@
map requirements
================
##Overview
## Overview
Map is a module that implements a dictionary of STRING_HANDLE key to STRING_HANDLE values.
##References
## References
[strings_requiremens.md]
[json.org](http://www.json.org)
##Exposed API
## Exposed API
```c
#define MAP_RESULT_VALUES \
@ -19,137 +19,177 @@ Map is a module that implements a dictionary of STRING_HANDLE key to STRING_HAND
MAP_INVALIDARG, \
MAP_KEYEXISTS, \
MAP_KEYNOTFOUND, \
MAP_FILTER_REJECT
MAP_FILTER_REJECT
DEFINE_ENUM(MAP_RESULT, MAP_RESULT_VALUES);
typedef void* MAP_HANDLE;
typedef int (*MAP_FILTER_CALLBACK)(const char* mapProperty, const char* mapValue);
extern MAP_HANDLE Map_Create(MAP_FILTER_CALLBACK mapFilterFunc);
extern void Map_Destroy(MAP_HANDLE handle);
extern MAP_HANDLE Map_Clone(MAP_HANDLE handle);
extern MAP_RESULT Map_Add(MAP_HANDLE handle, const char* key, const char* value);
extern MAP_RESULT Map_AddOrUpdate(MAP_HANDLE handle, const char* key, const char* value);
extern MAP_RESULT Map_Delete(MAP_HANDLE handle, const char* key);
extern MAP_RESULT Map_ContainsKey(MAP_HANDLE handle, const char* key, bool* keyExists);
extern MAP_RESULT Map_ContainsValue(MAP_HANDLE handle, const char* value, bool* valueExists);
extern STRING_HANDLE Map_GetValueFromKey(MAP_HANDLE handle, const char* key);
extern MAP_RESULT Map_GetInternals(MAP_HANDLE handle, const char*const** keys, const char*const** values, size_t* count);
extern STRING_HANDLE Map_ToJSON(MAP_HANDLE handle);
```
###Map_Create
### Map_Create
```c
extern MAP_HANDLE Map_Create(MAP_FILTER_CALLBACK mapFilterFunc);
```
**SRS_MAP_02_001: [**Map_Create shall create a new, empty map.**]**
**SRS_MAP_02_002: [**If during creation there are any error, then Map_Create shall return NULL.**]**
**SRS_MAP_02_003: [**Otherwise, it shall return a non-NULL handle that can be used in subsequent calls.**]**
###Map_Destroy
**SRS_MAP_02_001: [** Map_Create shall create a new, empty map. **]**
**SRS_MAP_02_002: [** If during creation there are any error, then Map_Create shall return NULL. **]**
**SRS_MAP_02_003: [** Otherwise, it shall return a non-NULL handle that can be used in subsequent calls. **]**
### Map_Destroy
```c
extern void Map_Destroy(MAP_HANDLE handle);
```
**SRS_MAP_02_004: [**Map_Destroy shall release all resources associated with the map.**]**
**SRS_MAP_02_005: [**If parameter handle is NULL then Map_Destroy shall take no action.**]**
###Map_Clone
```
**SRS_MAP_02_004: [** Map_Destroy shall release all resources associated with the map. **]**
**SRS_MAP_02_005: [** If parameter handle is NULL then Map_Destroy shall take no action. **]**
### Map_Clone
```c
extern MAP_HANDLE Map_Clone(MAP_HANDLE handle);
```
**SRS_MAP_02_038: [**Map_Clone returns NULL if parameter handle is NULL.**]**
**SRS_MAP_02_039: [**Map_Clone shall make a copy of the map indicated by parameter handle and return a non-NULL handle to it.**]**
**SRS_MAP_02_047: [**If during cloning, any operation fails, then Map_Clone shall return NULL.**]**
**SRS_MAP_02_038: [** Map_Clone returns NULL if parameter handle is NULL. **]**
###Map_Add
**SRS_MAP_02_039: [** Map_Clone shall make a copy of the map indicated by parameter handle and return a non-NULL handle to it. **]**
**SRS_MAP_02_047: [** If during cloning, any operation fails, then Map_Clone shall return NULL. **]**
### Map_Add
```c
extern MAP_RESULT Map_Add(MAP_HANDLE handle, const char* key, const char* value);
```
Map_Add adds to the map a pair of key, value.
**SRS_MAP_02_006: [**If parameter handle is NULL then Map_Add shall return MAP_INVALID_ARG.**]**
**SRS_MAP_02_007: [**If parameter key is NULL then Map_Add shall return MAP_INVALID_ARG.**]**
**SRS_MAP_02_008: [**If parameter value is NULL then Map_Add shall return MAP_INVALID_ARG.**]**
**SRS_MAP_02_009: [**If the key already exists, then Map_Add shall return MAP_KEYEXISTS.**]**
**SRS_MAP_02_010: [**Otherwise, Map_Add shall add the pair <key,value> to the map.**]**
**SRS_MAP_02_011: [**If adding the pair <key,value> fails then Map_Add shall return MAP_ERROR.**]**
**SRS_MAP_02_012: [**Otherwise, Map_Add shall return MAP_OK.**]**
**SRS_MAP_07_009: [**If the mapFilterCallback function is not NULL, then the return value will be checked and if it is not zero then Map_Add shall return MAP_FILTER_REJECT.**]**
###Map_AddOrUpdate
**SRS_MAP_02_006: [** If parameter handle is NULL then Map_Add shall return MAP_INVALID_ARG. **]**
**SRS_MAP_02_007: [** If parameter key is NULL then Map_Add shall return MAP_INVALID_ARG. **]**
**SRS_MAP_02_008: [** If parameter value is NULL then Map_Add shall return MAP_INVALID_ARG. **]**
**SRS_MAP_02_009: [** If the key already exists, then Map_Add shall return MAP_KEYEXISTS. **]**
**SRS_MAP_02_010: [** Otherwise, Map_Add shall add the pair <key,value> to the map. **]**
**SRS_MAP_02_011: [** If adding the pair <key,value> fails then Map_Add shall return MAP_ERROR. **]**
**SRS_MAP_02_012: [** Otherwise, Map_Add shall return MAP_OK. **]**
**SRS_MAP_07_009: [** If the mapFilterCallback function is not NULL, then the return value will be checked and if it is not zero then Map_Add shall return MAP_FILTER_REJECT. **]**
### Map_AddOrUpdate
```c
extern MAP_RESULT Map_AddOrUpdate(MAP_HANDLE, const char* key, const char* value);
```
**SRS_MAP_02_013: [**If parameter handle is NULL then Map_AddOrUpdate shall return MAP_INVALID_ARG.**]**
**SRS_MAP_02_014: [**If parameter key is NULL then Map_AddOrUpdate shall return MAP_INVALID_ARG.**]**
**SRS_MAP_02_015: [**If parameter value is NULL then Map_AddOrUpdate shall return MAP_INVALID_ARG.**]**
**SRS_MAP_02_016: [**If the key already exists, then Map_AddOrUpdate shall overwrite the value of the existing key with parameter value.**]**
**SRS_MAP_02_017: [**Otherwise, Map_AddOrUpdate shall add the pair <key,value> to the map.**]**
**SRS_MAP_02_018: [**If there are any failures then Map_AddOrUpdate shall return MAP_ERROR.**]**
**SRS_MAP_02_019: [**Otherwise, Map_AddOrUpdate shall return MAP_OK.**]**
**SRS_MAP_07_008: [**If the mapFilterCallback function is not NULL, then the return value will be check and if it is not zero then Map_AddOrUpdate shall return MAP_FILTER_REJECT.**]**
###Map_Delete
**SRS_MAP_02_013: [** If parameter handle is NULL then Map_AddOrUpdate shall return MAP_INVALID_ARG. **]**
**SRS_MAP_02_014: [** If parameter key is NULL then Map_AddOrUpdate shall return MAP_INVALID_ARG. **]**
**SRS_MAP_02_015: [** If parameter value is NULL then Map_AddOrUpdate shall return MAP_INVALID_ARG. **]**
**SRS_MAP_02_016: [** If the key already exists, then Map_AddOrUpdate shall overwrite the value of the existing key with parameter value. **]**
**SRS_MAP_02_017: [** Otherwise, Map_AddOrUpdate shall add the pair <key,value> to the map. **]**
**SRS_MAP_02_018: [** If there are any failures then Map_AddOrUpdate shall return MAP_ERROR. **]**
**SRS_MAP_02_019: [** Otherwise, Map_AddOrUpdate shall return MAP_OK. **]**
**SRS_MAP_07_008: [** If the mapFilterCallback function is not NULL, then the return value will be check and if it is not zero then Map_AddOrUpdate shall return MAP_FILTER_REJECT. **]**
### Map_Delete
```c
extern MAP_RESULT Map_Delete(MAP_HANDLE handle, const char* key);
```
Map_Delete removes a key and its associated value from the map.
**SRS_MAP_02_020: [**If parameter handle is NULL then Map_Delete shall return MAP_INVALIDARG.**]**
**SRS_MAP_02_021: [**If parameter key is NULL then Map_Delete shall return MAP_INVALIDARG.**]**
**SRS_MAP_02_022: [**If key does not exist then Map_Delete shall return MAP_KEYNOTFOUND.**]**
**SRS_MAP_02_023: [**Otherwise, Map_Delete shall remove the key and its associated value from the map and return MAP_OK.**]**
###Map_ContainsKey
**SRS_MAP_02_020: [** If parameter handle is NULL then Map_Delete shall return MAP_INVALIDARG. **]**
**SRS_MAP_02_021: [** If parameter key is NULL then Map_Delete shall return MAP_INVALIDARG. **]**
**SRS_MAP_02_022: [** If key does not exist then Map_Delete shall return MAP_KEYNOTFOUND. **]**
**SRS_MAP_02_023: [** Otherwise, Map_Delete shall remove the key and its associated value from the map and return MAP_OK. **]**
### Map_ContainsKey
```c
extern MAP_RESULT Map_ContainsKey(MAP_HANDLE handle, const char* key, bool* keyExists);
```
Map_ContainsKey returns in parameter keyExists if the map contains a key with the same value as parameter key.
**SRS_MAP_02_024: [**If parameter handle, key or keyExists are NULL then Map_ContainsKey shall return MAP_INVALIDARG.**]**
**SRS_MAP_02_025: [**Otherwise if a key exists then Map_ContainsKey shall return MAP_OK and shall write in keyExists "true".**]**
**SRS_MAP_02_026: [**If a key doesn't exist, then Map_ContainsKey shall return MAP_OK and write in keyExists "false".**]**
###Map_ContainsValue
**SRS_MAP_02_024: [** If parameter handle, key or keyExists are NULL then Map_ContainsKey shall return MAP_INVALIDARG. **]**
**SRS_MAP_02_025: [** Otherwise if a key exists then Map_ContainsKey shall return MAP_OK and shall write in keyExists "true". **]**
**SRS_MAP_02_026: [** If a key doesn't exist, then Map_ContainsKey shall return MAP_OK and write in keyExists "false". **]**
### Map_ContainsValue
```c
extern MAP_RESULT Map_ContainsValue(MAP_HANDLE handle, const char* value, bool* valueExists);
```
Map_ContainsKey returns in valueExists if at least one pair <key,value> in the map contains the value parameter.
**SRS_MAP_02_027: [**If parameter handle, value or valueExists is NULL then Map_ContainsValue shall return MAP_INVALIDARG.**]**
**SRS_MAP_02_028: [**Otherwise, if a pair <key, value> has its value equal to the parameter value, the Map_ContainsValue shall return MAP_OK and shall write in valueExists "true".**]**
**SRS_MAP_02_029: [**Otherwise, if such a <key, value> does not exist, then Map_ContainsValue shall return MAP_OK and shall write in valueExists "false".**]**
###Map_GetValueFromKey
**SRS_MAP_02_027: [** If parameter handle, value or valueExists is NULL then Map_ContainsValue shall return MAP_INVALIDARG. **]**
**SRS_MAP_02_028: [** Otherwise, if a pair <key, value> has its value equal to the parameter value, the Map_ContainsValue shall return MAP_OK and shall write in valueExists "true". **]**
**SRS_MAP_02_029: [** Otherwise, if such a <key, value> does not exist, then Map_ContainsValue shall return MAP_OK and shall write in valueExists "false". **]**
### Map_GetValueFromKey
```c
extern const char* Map_GetValueFromKey(MAP_HANDLE handle, const char* key);
```
Map_GetValueFromKey returns the value of a stored key.
**SRS_MAP_02_040: [**If parameter handle or key is NULL then Map_GetValueFromKey returns NULL.**]**
**SRS_MAP_02_041: [**If the key is not found, then Map_GetValueFromKey returns NULL.**]**
**SRS_MAP_02_042: [**Otherwise, Map_GetValueFromKey returns the key's value.**]**
###Map_GetInternals
**SRS_MAP_02_040: [** If parameter handle or key is NULL then Map_GetValueFromKey returns NULL. **]**
**SRS_MAP_02_041: [** If the key is not found, then Map_GetValueFromKey returns NULL. **]**
**SRS_MAP_02_042: [** Otherwise, Map_GetValueFromKey returns the key's value. **]**
### Map_GetInternals
```c
extern MAP_RESULT Map_GetInternals(MAP_HANDLE handle, const char*const** keys, const char*const** values, size_t* count);
```
**SRS_MAP_02_046: [**If parameter handle, keys, values or count is NULL then Map_GetInternals shall return MAP_INVALIDARG.**]**
**SRS_MAP_02_043: [**Map_GetInternals shall produce in *keys an pointer to an array of const char* having all the keys stored so far by the map.**]**
**SRS_MAP_02_044: [**Map_GetInternals shall produce in *values a pointer to an array of const char* having all the values stored so far by the map.**]**
**SRS_MAP_02_045: [** Map_GetInternals shall produce in *count the number of stored keys and values.**]**
**SRS_MAP_02_046: [** If parameter handle, keys, values or count is NULL then Map_GetInternals shall return MAP_INVALIDARG. **]**
###Map_ToJSON
**SRS_MAP_02_043: [** Map_GetInternals shall produce in *keys an pointer to an array of const char* having all the keys stored so far by the map. **]**
**SRS_MAP_02_044: [** Map_GetInternals shall produce in *values a pointer to an array of const char* having all the values stored so far by the map. **]**
**SRS_MAP_02_045: [** Map_GetInternals shall produce in *count the number of stored keys and values. **]**
### Map_ToJSON
```c
extern STRING_HANDLE Map_ToJSON(MAP_HANDLE handle);
```
**SRS_MAP_02_052: [**If parameter handle is NULL then Map_ToJSON shall return NULL.**]**
**SRS_MAP_02_048: [**Map_ToJSON shall produce a STRING_HANDLE representing the content of the MAP.**]**
**SRS_MAP_02_049: [**If the MAP is empty, then Map_ToJSON shall produce the string "{}".**]**
**SRS_MAP_02_050: [**If the map has properties then Map_ToJSON shall produce the following string:{"name1":"value1", "name2":"value2" ...}**]**
**SRS_MAP_02_051: [**If any error occurs while producing the output, then Map_ToJSON shall fail and return NULL.**]**
**SRS_MAP_02_052: [** If parameter handle is NULL then Map_ToJSON shall return NULL. **]**
**SRS_MAP_02_048: [** Map_ToJSON shall produce a STRING_HANDLE representing the content of the MAP. **]**
**SRS_MAP_02_049: [** If the MAP is empty, then Map_ToJSON shall produce the string "{}". **]**
**SRS_MAP_02_050: [** If the map has properties then Map_ToJSON shall produce the following string:{"name1":"value1", "name2":"value2" ...} **]**
**SRS_MAP_02_051: [** If any error occurs while producing the output, then Map_ToJSON shall fail and return NULL. **]**

32
devdoc/optionhandler_requirements.md
Просмотреть файл

@ -48,59 +48,81 @@ MOCKABLE_FUNCTION(,void, OptionHandler_Destroy, OPTIONHANDLER_HANDLE, handle);
}
#endif /* __cplusplus */
### OptionHandler_Create
### OptionHandler_Create
```c
OPTIONHANDLER_HANDLE OptionHandler_Create(pfCloneOption cloneOption, pfDestroyOption destroyOption, pfSetOption setOption)
```
**SRS_OPTIONHANDLER_02_001: [** `OptionHandler_Create` shall fail and retun `NULL` if any parameters are `NULL`. **]**
**SRS_OPTIONHANDLER_02_002: [** `OptionHandler_Create` shall create an empty VECTOR that will hold pairs of `const char*` and `void*`. **]**
**SRS_OPTIONHANDLER_02_003: [** If all the operations succeed then `OptionHandler_Create` shall succeed and return a non-`NULL` handle. **]**
**SRS_OPTIONHANDLER_02_004: [** Otherwise, `OptionHandler_Create` shall fail and return `NULL`. **]**
### OptionHandler_Clone
### OptionHandler_Clone
```c
OPTIONHANDLER_HANDLE OptionHandler_Clone(OPTIONHANDLER_HANDLE handler);
```
**SRS_OPTIONHANDLER_01_001: [** `OptionHandler_Clone` shall clone an existing option handler instance. **]**
**SRS_OPTIONHANDLER_01_002: [** On success it shall return a non-NULL handle. **]**
**SRS_OPTIONHANDLER_01_010: [** If `handler` is NULL, OptionHandler_Clone shall fail and return NULL. **]**
**SRS_OPTIONHANDLER_01_003: [** `OptionHandler_Clone` shall allocate memory for the new option handler instance. **]**
**SRS_OPTIONHANDLER_01_004: [** If allocating memory fails, `OptionHandler_Clone` shall return NULL. **]**
**SRS_OPTIONHANDLER_01_005: [** `OptionHandler_Clone` shall iterate through all the options stored by the option handler to be cloned by using VECTOR's iteration mechanism. **]**
**SRS_OPTIONHANDLER_01_006: [** For each option the option name shall be cloned by calling `mallocAndStrcpy_s`. **]**
**SRS_OPTIONHANDLER_01_007: [** For each option the value shall be cloned by using the cloning function associated with the source option handler `handler`. **]**
**SRS_OPTIONHANDLER_01_008: [** If cloning one of the option names fails, `OptionHandler_Clone` shall return NULL. **]**
**SRS_OPTIONHANDLER_01_009: [** If cloning one of the option values fails, `OptionHandler_Clone` shall return NULL. **]**
**SRS_OPTIONHANDLER_01_011: [** When adding one of the newly cloned options to the option handler storage vector fails, `OptionHandler_Clone` shall return NULL. **]**
### OptionHandler_AddOption
### OptionHandler_AddOption
```c
OPTIONHANDLER_RESULT OptionHandler_AddOption(OPTIONHANDLER_HANDLE handle, const char* name, void* value)
```
**SRS_OPTIONHANDLER_02_005: [** `OptionHandler_AddOption` shall fail and return `OPTIONHANDLER_INVALIDARG` if any parameter is NULL. **]**
**SRS_OPTIONHANDLER_02_006: [** OptionHandler_AddOption shall call `pfCloneOption` passing `name` and `value`. **]**
**SRS_OPTIONHANDLER_02_007: [** OptionHandler_AddOption shall use `VECTOR` APIs to save the `name` and the newly created clone of `value`. **]**
**SRS_OPTIONHANDLER_02_008: [** If all the operations succed then `OptionHandler_AddOption` shall succeed and return `OPTIONHANDLER_OK`. **]**
**SRS_OPTIONHANDLER_02_009: [** Otherwise, `OptionHandler_AddOption` shall succeed and return `OPTIONHANDLER_ERROR`. **]**
### OptionHandler_FeedOptions
### OptionHandler_FeedOptions
```c
OPTIONHANDLER_RESULT OptionHandler_FeedOptions(OPTIONHANDLER_HANDLE handle, void* destinationHandle);
```
**SRS_OPTIONHANDLER_02_010: [** `OptionHandler_FeedOptions` shall fail and return `OPTIONHANDLER_INVALIDARG` if any argument is `NULL`. **]**
**SRS_OPTIONHANDLER_02_011: [** Otherwise, `OptionHandler_FeedOptions` shall use `VECTOR`'s iteration mechanisms to retrieve pairs of name, value (`const char*` and `void*`). **]**
**SRS_OPTIONHANDLER_02_012: [** `OptionHandler_FeedOptions` shall call for every pair of name,value `setOption` passing `destinationHandle`, name and value. **]**
**SRS_OPTIONHANDLER_02_013: [** If all the operations succeed then `OptionHandler_FeedOptions` shall succeed and return `OPTIONHANDLER_OK`. **]**
**SRS_OPTIONHANDLER_02_014: [** Otherwise, `OptionHandler_FeedOptions` shall fail and return `OPTIONHANDLER_ERROR`. **]**
### OptionHandler_Destroy
### OptionHandler_Destroy
```c
void OptionHandler_Destroy(OPTIONHANDLER_HANDLE handle)
```
**SRS_OPTIONHANDLER_02_015: [** OptionHandler_Destroy shall do nothing if parameter `handle` is `NULL`. **]**
**SRS_OPTIONHANDLER_02_016: [** Otherwise, OptionHandler_Destroy shall free all used resources. **]**

14
devdoc/platform_arduino_requirements.md
Просмотреть файл

@ -8,7 +8,7 @@ platform_arduino implements a standart way for SDK to access dedicated Arduino i
## References
### Standard
### Standard
**SRS_PLATFORM_ARDUINO_21_001: [** The platform_arduino shall implement the interface provided in the `platfom.h`.
```c
@ -16,7 +16,7 @@ platform_arduino implements a standart way for SDK to access dedicated Arduino i
MOCKABLE_FUNCTION(, void, platform_deinit);
MOCKABLE_FUNCTION(, const IO_INTERFACE_DESCRIPTION*, platform_get_default_tlsio);
```
**]**
**]**
**SRS_PLATFORM_ARDUINO_21_002: [** The platform_arduino shall use the tlsio functions defined by the 'xio.h'.
```c
@ -41,29 +41,31 @@ typedef struct IO_INTERFACE_DESCRIPTION_TAG
IO_SETOPTION concrete_io_setoption;
} IO_INTERFACE_DESCRIPTION;
```
**]**
**]**
### platform_init
### platform_init
```c
int platform_init(void)
```
**SRS_PLATFORM_ARDUINO_21_003: [** The platform_init shall initialize the platform. **]**
**SRS_PLATFORM_ARDUINO_21_004: [** The platform_init shall allocate any memory needed to control the platform. **]**
### platform_deinit
### platform_deinit
```c
int platform_deinit(void)
```
**SRS_PLATFORM_ARDUINO_21_005: [** The platform_deinit shall deinitialize the platform. **]**
**SRS_PLATFORM_ARDUINO_21_006: [** The platform_deinit shall free all allocate memory needed to control the platform. **]**
### platform_get_default_tlsio
### platform_get_default_tlsio
```c
const IO_INTERFACE_DESCRIPTION* platform_get_default_tlsio(void)

15
devdoc/platform_openssl_compact_requirements.md
Просмотреть файл

@ -13,7 +13,7 @@ initialization and deinitialization using the interfaces in `azure-c-shared-util
## References
[sntp.h](https://github.com/Azure/azure-c-shared-utility/tree/master/inc/azure_c_shared_utility/sntp.h)
### Standard
### Standard
**SRS_PLATFORM_OPENSSL_COMPACT_30_001: [** The platform_openssl_compact shall implement the interface provided in the `platfom.h`.
@ -23,7 +23,7 @@ initialization and deinitialization using the interfaces in `azure-c-shared-util
void platform_deinit();
const IO_INTERFACE_DESCRIPTION* platform_get_default_tlsio();
```
**]**
**]**
**SRS_PLATFORM_OPENSSL_COMPACT_30_002: [** The platform_openssl_compact shall use the tlsio functions defined in 'xio.h'.
```c
@ -48,7 +48,7 @@ typedef struct IO_INTERFACE_DESCRIPTION_TAG
IO_SETOPTION concrete_io_setoption;
} IO_INTERFACE_DESCRIPTION;
```
**]**
**]**
**SRS_PLATFORM_OPENSSL_COMPACT_30_003: [** The platform_openssl_compact shall use the sntp functions defined in 'sntp.h'.
```c
@ -56,9 +56,9 @@ int SNTP_SetServerName(const char*, serverName);
int SNTP_Init();
void SNTP_Deinit();
```
**]**
**]**
### platform_init
### platform_init
The `platform_init` call performs initialization for the compact (microcontroller) version of the OpenSSL tlsio adapter plus sntp client initialization.
@ -67,10 +67,11 @@ int platform_init();
```
**SRS_PLATFORM_OPENSSL_COMPACT_30_004: [** The platform_init shall initialize the tlsio adapter. **]**
**SRS_PLATFORM_OPENSSL_COMPACT_30_005: [** The platform_init shall initialize the sntp client. **]**
### platform_deinit
### platform_deinit
```c
int platform_deinit();
@ -79,7 +80,7 @@ int platform_deinit();
**SRS_PLATFORM_OPENSSL_COMPACT_30_006: [** The platform_deinit shall deinitialize the sntp client. (The OpenSSL micro tlsio adapter requires no deinitialization.) **]**
### platform_get_default_tlsio
### platform_get_default_tlsio
```c
const IO_INTERFACE_DESCRIPTION* platform_get_default_tlsio(void);

100
devdoc/sastoken_requirements.md
Просмотреть файл

@ -1,63 +1,89 @@
sastoken requirements
================
##Overview
## Overview
This function is used to create a SAS token.
##References
## References
[Keyed-Hashing for Message Authentication, RFC2104](https://www.ietf.org/rfc/rfc2104.txt)
[SASToken format](https://azure.microsoft.com/en-us/documentation/articles/storage-dotnet-shared-access-signature-part-1/)
##Exposed API
## Exposed API
```c
MOCKABLE_FUNCTION(, bool, SASToken_Validate, STRING_HANDLE, sasToken);
MOCKABLE_FUNCTION(, STRING_HANDLE, SASToken_Create, STRING_HANDLE, key, STRING_HANDLE, scope, STRING_HANDLE, keyName, size_t, expiry);
```
###SASToken_Create
### SASToken_Create
```c
extern STRING_HANDLE SASToken_Create(STRING_HANDLE key, STRING_HANDLE scope, STRING_HANDLE keyName, size_t expiry);
```
**SRS_SASTOKEN_06_001: [**If key is NULL then SASToken_Create shall return NULL.**]**
**SRS_SASTOKEN_06_003: [**If scope is NULL then SASToken_Create shall return NULL.**]**
**SRS_SASTOKEN_06_007: [**If keyName is NULL then SASToken_Create shall return NULL.**]**
**SRS_SASTOKEN_06_029: [**The key parameter is decoded from base64.**]**
**SRS_SASTOKEN_06_030: [**If there is an error in the decoding then SASToken_Create shall return NULL.**]** The decoded value shall henceforth be known as decodedKey.
**SRS_SASTOKEN_06_001: [** If key is NULL then SASToken_Create shall return NULL. **]**
**SRS_SASTOKEN_06_003: [** If scope is NULL then SASToken_Create shall return NULL. **]**
**SRS_SASTOKEN_06_007: [** If keyName is NULL then SASToken_Create shall return NULL. **]**
**SRS_SASTOKEN_06_029: [** The key parameter is decoded from base64. **]**
**SRS_SASTOKEN_06_030: [** If there is an error in the decoding then SASToken_Create shall return NULL. **]** The decoded value shall henceforth be known as decodedKey.
The expiry argument shall be converted to a char* by invoking size_tToString.
**SRS_SASTOKEN_06_026: [**If the conversion to string form fails for any reason then SASToken_Create shall return NULL.**]** The string shall be henceforth referred to as tokenExpirationTime.
**SRS_SASTOKEN_06_009: [**The scope is the basis for creating a STRING_HANDLE.**]**
**SRS_SASTOKEN_06_010: [**A "\n" is appended to that string.**]**
**SRS_SASTOKEN_06_011: [**tokenExpirationTime is appended to that string.**]** This is henceforth referred to as toBeHashed.
**SRS_SASTOKEN_06_012: [**An HMAC256 hash is calculated using the decodedKey, over toBeHashed.**]**
**SRS_SASTOKEN_06_013: [**If an error is returned from the HMAC256 function then NULL is returned from SASToken_Create.**]**
**SRS_SASTOKEN_06_014: [**If there are any errors from the following operations then NULL shall be returned.**]**
**SRS_SASTOKEN_06_015: [**The hash is base 64 encoded.**]** That (STRING_HANDLE) shall be called base64Signature.
**SRS_SASTOKEN_06_028: [**base64Signature shall be url encoded.**]** This (STRING_HANDLE) shall be called urlEncodedSignature.
**SRS_SASTOKEN_06_016: [**The string "SharedAccessSignature sr=" is the first part of the result of SASToken_Create.**]**
**SRS_SASTOKEN_06_017: [**The scope parameter is appended to result.**]**
**SRS_SASTOKEN_06_018: [**The string "&sig=" is appended to result.**]**
**SRS_SASTOKEN_06_019: [**The string urlEncodedSignature shall be appended to result.**]**
**SRS_SASTOKEN_06_020: [**The string "&se=" shall be appended to result.**]**
**SRS_SASTOKEN_06_021: [**tokenExpirationTime is appended to result.**]**
**SRS_SASTOKEN_06_022: [**The string "&skn=" is appended to result.**]**
**SRS_SASTOKEN_06_023: [**The argument keyName is appended to result.**]**
**SRS_SASTOKEN_06_026: [** If the conversion to string form fails for any reason then SASToken_Create shall return NULL. **]** The string shall be henceforth referred to as tokenExpirationTime.
**SRS_SASTOKEN_06_009: [** The scope is the basis for creating a STRING_HANDLE. **]**
**SRS_SASTOKEN_06_010: [** A "\n" is appended to that string. **]**
**SRS_SASTOKEN_06_011: [** tokenExpirationTime is appended to that string. **]** This is henceforth referred to as toBeHashed.
**SRS_SASTOKEN_06_012: [** An HMAC256 hash is calculated using the decodedKey, over toBeHashed. **]**
**SRS_SASTOKEN_06_013: [** If an error is returned from the HMAC256 function then NULL is returned from SASToken_Create. **]**
**SRS_SASTOKEN_06_014: [** If there are any errors from the following operations then NULL shall be returned. **]**
**SRS_SASTOKEN_06_015: [** The hash is base 64 encoded. **]** That (STRING_HANDLE) shall be called base64Signature.
**SRS_SASTOKEN_06_028: [** base64Signature shall be url encoded. **]** This (STRING_HANDLE) shall be called urlEncodedSignature.
**SRS_SASTOKEN_06_016: [** The string "SharedAccessSignature sr=" is the first part of the result of SASToken_Create. **]**
**SRS_SASTOKEN_06_017: [** The scope parameter is appended to result. **]**
**SRS_SASTOKEN_06_018: [** The string "&sig=" is appended to result. **]**
**SRS_SASTOKEN_06_019: [** The string urlEncodedSignature shall be appended to result. **]**
**SRS_SASTOKEN_06_020: [** The string "&se=" shall be appended to result. **]**
**SRS_SASTOKEN_06_021: [** tokenExpirationTime is appended to result. **]**
**SRS_SASTOKEN_06_022: [** The string "&skn=" is appended to result. **]**
**SRS_SASTOKEN_06_023: [** The argument keyName is appended to result. **]**
result is returned.
###SASToken_Validate
### SASToken_Validate
```c
extern bool SASToken_Validate(STRING_HANDLE handle);
```
**SRS_SASTOKEN_25_024: [**If handle is NULL then SASToken_Validate shall return false.**]**
**SRS_SASTOKEN_25_025: [**SASToken_Validate shall get the SASToken value by invoking STRING_c_str on the handle.**]**
**SRS_SASTOKEN_25_026: [**If STRING_c_str on handle return NULL then SASToken_Validate shall return false.**]**
**SRS_SASTOKEN_25_027: [**If SASTOKEN does not obey the SASToken format then SASToken_Validate shall return false.**]**
**SRS_SASTOKEN_25_028: [**SASToken_validate shall check for the presence of sr, se and sig from the token and return false if not found**]**
**SRS_SASTOKEN_25_029: [**SASToken_validate shall check for expiry time from token and if token has expired then would return false **]**
**SRS_SASTOKEN_25_030: [**SASToken_validate shall return true only if the format is obeyed and the token has not yet expired **]**
**SRS_SASTOKEN_25_031: [**If malloc fails during validation then SASToken_Validate shall return false.**]**
**SRS_SASTOKEN_25_024: [** If handle is NULL then SASToken_Validate shall return false. **]**
**SRS_SASTOKEN_25_025: [** SASToken_Validate shall get the SASToken value by invoking STRING_c_str on the handle. **]**
**SRS_SASTOKEN_25_026: [** If STRING_c_str on handle return NULL then SASToken_Validate shall return false. **]**
**SRS_SASTOKEN_25_027: [** If SASTOKEN does not obey the SASToken format then SASToken_Validate shall return false. **]**
**SRS_SASTOKEN_25_028: [** SASToken_validate shall check for the presence of sr, se and sig from the token and return false if not found **]**
**SRS_SASTOKEN_25_029: [** SASToken_validate shall check for expiry time from token and if token has expired then would return false **]**
**SRS_SASTOKEN_25_030: [** SASToken_validate shall return true only if the format is obeyed and the token has not yet expired **]**
**SRS_SASTOKEN_25_031: [** If malloc fails during validation then SASToken_Validate shall return false. **]**

101
devdoc/singlylinkedlist_requirements.md
Просмотреть файл

@ -1,11 +1,11 @@
singlylinkedlist requirements
================
##Overview
## Overview
SinglyLinkedList is module that provides the functionality of a singly linked list, allowing its user to add, remove and iterate the list elements.
##Exposed API
## Exposed API
```c
typedef struct SINGLYLINKEDLIST_INSTANCE_TAG* SINGLYLINKEDLIST_HANDLE;
@ -24,73 +24,90 @@ extern int singlylinkedlist_remove_matching_item(SINGLYLINKEDLIST_HANDLE list, L
extern const void* singlylinkedlist_item_get_value(LIST_ITEM_HANDLE item_handle);
```
###singlylinkedlist_create
### singlylinkedlist_create
```c
extern SINGLYLINKEDLIST_HANDLE singlylinkedlist_create(void);
```
**SRS_LIST_01_001: [**singlylinkedlist_create shall create a new list and return a non-NULL handle on success.**]**
**SRS_LIST_01_002: [**If any error occurs during the list creation, singlylinkedlist_create shall return NULL.**]**
###singlylinkedlist_destroy
**SRS_LIST_01_001: [** singlylinkedlist_create shall create a new list and return a non-NULL handle on success. **]**
**SRS_LIST_01_002: [** If any error occurs during the list creation, singlylinkedlist_create shall return NULL. **]**
### singlylinkedlist_destroy
```c
extern void singlylinkedlist_destroy(SINGLYLINKEDLIST_HANDLE list);
```
**SRS_LIST_01_003: [**singlylinkedlist_destroy shall free all resources associated with the list identified by the handle argument.**]**
**SRS_LIST_01_004: [**If the list argument is NULL, no freeing of resources shall occur.**]**
###singlylinkedlist_add
**SRS_LIST_01_003: [** singlylinkedlist_destroy shall free all resources associated with the list identified by the handle argument. **]**
**SRS_LIST_01_004: [** If the list argument is NULL, no freeing of resources shall occur. **]**
### singlylinkedlist_add
```c
extern int singlylinkedlist_add(SINGLYLINKEDLIST_HANDLE list, const void* item);
```
**SRS_LIST_01_005: [**singlylinkedlist_add shall add one item to the tail of the list and on success it shall return a handle to the added item.**]**
**SRS_LIST_01_006: [**If any of the arguments is NULL, singlylinkedlist_add shall not add the item to the list and return NULL.**]**
**SRS_LIST_01_007: [**If allocating the new list node fails, singlylinkedlist_add shall return NULL.**]**
###singlylinkedlist_get_head_item
**SRS_LIST_01_005: [** singlylinkedlist_add shall add one item to the tail of the list and on success it shall return a handle to the added item. **]**
**SRS_LIST_01_006: [** If any of the arguments is NULL, singlylinkedlist_add shall not add the item to the list and return NULL. **]**
**SRS_LIST_01_007: [** If allocating the new list node fails, singlylinkedlist_add shall return NULL. **]**
### singlylinkedlist_get_head_item
```c
extern const void* singlylinkedlist_get_head_item(SINGLYLINKEDLIST_HANDLE list);
```
**SRS_LIST_01_008: [**singlylinkedlist_get_head_item shall return the head of the list.**]**
**SRS_LIST_01_009: [**If the list argument is NULL, singlylinkedlist_get_head_item shall return NULL.**]**
**SRS_LIST_01_010: [**If the list is empty, list_get_head_item_shall_return NULL.**]**
###singlylinkedlist_get_next_item
**SRS_LIST_01_008: [** singlylinkedlist_get_head_item shall return the head of the list. **]**
**SRS_LIST_01_009: [** If the list argument is NULL, singlylinkedlist_get_head_item shall return NULL. **]**
**SRS_LIST_01_010: [** If the list is empty, list_get_head_item_shall_return NULL. **]**
### singlylinkedlist_get_next_item
```c
extern LIST_ITEM_HANDLE singlylinkedlist_get_next_item(LIST_ITEM_HANDLE item_handle);
```
**SRS_LIST_01_018: [**singlylinkedlist_get_next_item shall return the next item in the list following the item item_handle.**]**
**SRS_LIST_01_019: [**If item_handle is NULL then singlylinkedlist_get_next_item shall return NULL.**]**
**SRS_LIST_01_022: [**If no more items exist in the list after the item_handle item, singlylinkedlist_get_next_item shall return NULL.**]**
**SRS_LIST_01_018: [** singlylinkedlist_get_next_item shall return the next item in the list following the item item_handle. **]**
###singlylinkedlist_find
**SRS_LIST_01_019: [** If item_handle is NULL then singlylinkedlist_get_next_item shall return NULL. **]**
**SRS_LIST_01_022: [** If no more items exist in the list after the item_handle item, singlylinkedlist_get_next_item shall return NULL. **]**
### singlylinkedlist_find
```c
extern const void* singlylinkedlist_find(SINGLYLINKEDLIST_HANDLE list, const void* match_context, LIST_MATCH_FUNCTION match_function);
```
**SRS_LIST_01_011: [**singlylinkedlist_find shall iterate through all items in a list and return the first one that satisfies a certain match function.**]**
**SRS_LIST_01_012: [**If the list or the match_function argument is NULL, singlylinkedlist_find shall return NULL.**]**
**SRS_LIST_01_014: [**list find shall determine whether an item satisfies the match criteria by invoking the match function for each item in the list until a matching item is found.**]**
**SRS_LIST_01_013: [**The match_function shall get as arguments the list item being attempted to be matched and the match_context as is.**]**
**SRS_LIST_01_016: [**If the match function returns false, singlylinkedlist_find shall consider that item as not matching.**]**
**SRS_LIST_01_017: [**If the match function returns true, singlylinkedlist_find shall consider that item as matching.**]**
**SRS_LIST_01_015: [**If the list is empty, singlylinkedlist_find shall return NULL.**]**
###singlylinkedlist_remove
**SRS_LIST_01_011: [** singlylinkedlist_find shall iterate through all items in a list and return the first one that satisfies a certain match function. **]**
**SRS_LIST_01_012: [** If the list or the match_function argument is NULL, singlylinkedlist_find shall return NULL. **]**
**SRS_LIST_01_014: [** list find shall determine whether an item satisfies the match criteria by invoking the match function for each item in the list until a matching item is found. **]**
**SRS_LIST_01_013: [** The match_function shall get as arguments the list item being attempted to be matched and the match_context as is. **]**
**SRS_LIST_01_016: [** If the match function returns false, singlylinkedlist_find shall consider that item as not matching. **]**
**SRS_LIST_01_017: [** If the match function returns true, singlylinkedlist_find shall consider that item as matching. **]**
**SRS_LIST_01_015: [** If the list is empty, singlylinkedlist_find shall return NULL. **]**
### singlylinkedlist_remove
```c
extern int singlylinkedlist_remove(SINGLYLINKEDLIST_HANDLE list, LIST_ITEM_HANDLE item_handle);
```
**SRS_LIST_01_023: [**singlylinkedlist_remove shall remove a list item from the list and on success it shall return 0.**]**
**SRS_LIST_01_024: [**If any of the arguments list or item_handle is NULL, singlylinkedlist_remove shall fail and return a non-zero value.**]**
**SRS_LIST_01_025: [**If the item item_handle is not found in the list, then singlylinkedlist_remove shall fail and return a non-zero value.**]**
###singlylinkedlist_item_get_value
**SRS_LIST_01_023: [** singlylinkedlist_remove shall remove a list item from the list and on success it shall return 0. **]**
**SRS_LIST_01_024: [** If any of the arguments list or item_handle is NULL, singlylinkedlist_remove shall fail and return a non-zero value. **]**
**SRS_LIST_01_025: [** If the item item_handle is not found in the list, then singlylinkedlist_remove shall fail and return a non-zero value. **]**
### singlylinkedlist_item_get_value
```c
extern const void* singlylinkedlist_item_get_value(LIST_ITEM_HANDLE item_handle);
```
**SRS_LIST_01_020: [**singlylinkedlist_item_get_value shall return the value associated with the list item identified by the item_handle argument.**]**
**SRS_LIST_01_021: [**If item_handle is NULL, singlylinkedlist_item_get_value shall return NULL.**]**
**SRS_LIST_01_020: [** singlylinkedlist_item_get_value shall return the value associated with the list item identified by the item_handle argument. **]**
**SRS_LIST_01_021: [** If item_handle is NULL, singlylinkedlist_item_get_value shall return NULL. **]**

13
devdoc/sntp_lwip_requirements.md
Просмотреть файл

@ -11,7 +11,7 @@ and aimed at small devices because NTP's time setting function is taken care of
[lwIP](http://savannah.nongnu.org/projects/lwip/)
### Exposed API
### Exposed API
**SRS_SNTP_LWIP_30_001: [** The ntp_lwip shall implement the methods defined in `sntp.h`.
```c
@ -19,10 +19,10 @@ int SNTP_SetServerName(const char* serverName);
int SNTP_Init();
void SNTP_Deinit();
```
**]**
**]**
### SNTP_SetServerName
### SNTP_SetServerName
`SNTP_SetServerName` must be called before `SNTP_Init`. The character array pointed to by `serverName` parameter must persist between calls to `SNTP_SetServerName` and `SNTP_Deinit` because the char* is stored and no copy of the string is made.
`SNTP_SetServerName` is a wrapper for the lwIP call `sntp_setservername` and defers parameter validation to the lwIP library.
@ -33,13 +33,14 @@ void SNTP_Deinit();
int SNTP_SetServerName(const char* serverName);
```
**SRS_SNTP_LWIP_30_002: [** The `serverName` parameter shall be an NTP server URL which shall not be validated. (Validation is deferred to the underlying library.) **]**
**SRS_SNTP_LWIP_30_002: [** The `serverName` parameter shall be an NTP server URL which shall not be validated. (Validation is deferred to the underlying library.) **]**
**SRS_SNTP_LWIP_30_003: [** The `SNTP_SetServerName` shall set the NTP server
to be used by ntp_lwip and return 0 to indicate success. (lwIP has no failure path.) **]**
### SNTP_Init
### SNTP_Init
`SNTP_Init` initializes the SNTP client and begins the process of contacting the NTP server. It blocks until NTP time has been successfully received.
@ -49,7 +50,7 @@ int SNTP_Init();
**SRS_SNTP_LWIP_30_004: [** `SNTP_Init` shall initialize the SNTP client, contact the NTP server to set system time, then return 0 to indicate success (lwIP has no failure path). **]**
### SNTP_Denit
### SNTP_Denit
`SNTP_Denit` deinitializes the SNTP client.

26
devdoc/ssl_socket_compact.md
Просмотреть файл

@ -16,7 +16,7 @@ in the `SSL_Socket_Create` call defined in `ssl_socket.h`.
[ssl_socket.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/ssl_socket.h)
[sys/socket.h, a typical linux socket implementation](http://pubs.opengroup.org/onlinepubs/7908799/xns/syssocket.h.html)
### Exposed API
### Exposed API
**SRS_SSL_SOCKET_COMPACT_30_001: [** The ssl_socket_compact shall use the constants defined in `ssl_socket.h`.
```c
@ -25,17 +25,17 @@ in the `SSL_Socket_Create` call defined in `ssl_socket.h`.
#define AZURE_SSL_SOCKET_TCP_KEEPINTVL 2 /* seconds */
#define AZURE_SSL_SOCKET_TCP_KEEPCNT 3 /* retry count */
```
**]**
**]**
**SRS_SSL_SOCKET_COMPACT_30_001: [** The ssl_socket_compact shall implement the methods defined in `ssl_socket.h`.
```c
int SSL_Socket_Create(const char* hostname, int port);
void SSL_Socket_Close(int sock);
```
**]**
**]**
### SSL_Socket_Create
### SSL_Socket_Create
`SSL_Socket_Create` creates a socket and sets its configuration, including setting the socket to non-blocking. It then binds the socket to the supplied `hostname` and `port`, and finally connects the socket to the bound address.
If successful, it returns a non-negative integer to represent the socket's file descriptor. On failure, it returns -1.
@ -44,19 +44,28 @@ If successful, it returns a non-negative integer to represent the socket's file
int SSL_Socket_Create(const char* hostname, int port);
```
**SRS_SSL_SOCKET_COMPACT_30_002: [** The `hostname` parameter shall be the fully-qualified domain name (FQDN) of the target server. Example: azure-iot-team.azure-devices.net **]**
**SRS_SSL_SOCKET_COMPACT_30_002: [** The `hostname` parameter shall be the fully-qualified domain name (FQDN) of the target server. Example: azure-iot-team.azure-devices.net **]**
**SRS_SSL_SOCKET_COMPACT_30_003: [** The `port` shall be the TCP port number for the target server. **]**
**SRS_SSL_SOCKET_COMPACT_30_004: [** The `SO_KEEPALIVE` option value of the returned socket shall be `AZURE_SSL_SOCKET_SO_KEEPALIVE`. **]**
**SRS_SSL_SOCKET_COMPACT_30_005: [** The `TCP_KEEPIDLE` option value of the returned socket shall be `AZURE_SSL_SOCKET_TCP_KEEPIDLE`. **]**
**SRS_SSL_SOCKET_COMPACT_30_006: [** The `TCP_KEEPINTVL` option value of the returned socket shall be `AZURE_SSL_SOCKET_TCP_KEEPINTVL`. **]**
**SRS_SSL_SOCKET_COMPACT_30_007: [** The `TCP_KEEPCNT` option value of the returned socket shall be `AZURE_SSL_SOCKET_TCP_KEEPCNT`. **]**
**SRS_SSL_SOCKET_COMPACT_30_008: [** The returned socket shall be set to `O_NONBLOCK`. **]**
**SRS_SSL_SOCKET_COMPACT_30_009: [** If the `hostname` cannot be resolved by DNS lookup, `SSL_Socket_Create` shall return -1. **]**
**SRS_SSL_SOCKET_COMPACT_30_010: [** If socket binding fails, `SSL_Socket_Create` shall return -1. **]**
**SRS_SSL_SOCKET_COMPACT_30_009: [** If the `hostname` cannot be resolved by DNS lookup, `SSL_Socket_Create` shall return -1. **]**
**SRS_SSL_SOCKET_COMPACT_30_010: [** If socket binding fails, `SSL_Socket_Create` shall return -1. **]**
**SRS_SSL_SOCKET_COMPACT_30_011: [** If socket connection fails, `SSL_Socket_Create` shall return -1. **]**
### SSL_Socket_Close
### SSL_Socket_Close
`SSL_Socket_Close` calls the underlying socket `close()` on the supplied socket. Parameter validation is deferred to the underlying call, so no validation is performed by `SSL_Socket_Close`.
```c
@ -64,4 +73,5 @@ int SSL_Socket_Create(const char* hostname, int port);
```
**SRS_SSL_SOCKET_COMPACT_30_012: [** The `sock` parameter shall be the integer file descriptor of the socket to be closed. **]**
**SRS_SSL_SOCKET_COMPACT_30_013: [** `SSL_Socket_Close` shall call the underlying `close` method on the supplied socket. **]**

59
devdoc/string_tokenizer_requirements.md
Просмотреть файл

@ -7,38 +7,51 @@ The STRING TOKENIZER provides the functionality of splitting a STRING into multi
## Exposed API
```C
typedef struct STRING_TOKEN_TAG* STRING_TOKENIZER_HANDLE;
extern STRING_TOKENIZER_HANDLE STRING_TOKENIZER_create(STRING_HANDLE handle);
extern STRING_TOKENIZER_HANDLE STRING_TOKENIZER_create_from_char(const char* input);
extern int STRING_TOKENIZER_get_next_token(STRING_TOKENIZER_HANDLE t, STRING_HANDLE output, const char* delimiters);
extern void STRING_TOKENIZER_destroy(STRING_TOKENIZER_HANDLE t);
```
### STRING_TOKENIZER_create
### STRING_TOKENIZER_create
extern STRING_TOKENIZER_HANDLE STRING_TOKENIZER_create(STRING_HANDLE handle);
**SRS_STRING_TOKENIZER_04_001: [**STRING_TOKENIZER_create shall return an NULL STRING_TOKENIZER_HANDLE if parameter handle is NULL**]**
**SRS_STRING_TOKENIZER_04_002: [**STRING_TOKENIZER_create shall allocate a new STRING_TOKENIZER _HANDLE having the content of the STRING_HANDLE copied and current position pointing at the beginning of the string**]**
**SRS_STRING_TOKENIZER_04_003: [**STRING_TOKENIZER_create shall return an NULL STRING_TOKENIZER _HANDLE on any error that is encountered**]**
**SRS_STRING_TOKENIZER_04_001: [** STRING_TOKENIZER_create shall return an NULL STRING_TOKENIZER_HANDLE if parameter handle is NULL **]**
### STRING_TOKENIZER_create_from_char
**SRS_STRING_TOKENIZER_04_002: [** STRING_TOKENIZER_create shall allocate a new STRING_TOKENIZER _HANDLE having the content of the STRING_HANDLE copied and current position pointing at the beginning of the string **]**
**SRS_STRING_TOKENIZER_04_003: [** STRING_TOKENIZER_create shall return an NULL STRING_TOKENIZER _HANDLE on any error that is encountered **]**
### STRING_TOKENIZER_create_from_char
extern STRING_TOKENIZER_HANDLE STRING_TOKENIZER_create_from_char(const char* input);
**SRS_STRING_TOKENIZER_07_001: [**STRING_TOKENIZER_create_from_char shall return an NULL STRING_TOKENIZER_HANDLE if parameter input is NULL**]**
**SRS_STRING_TOKENIZER_07_002: [**STRING_TOKENIZER_create_from_char shall allocate a new STRING_TOKENIZER _HANDLE having the content of the STRING_HANDLE copied and current position pointing at the beginning of the string**]**
**SRS_STRING_TOKENIZER_07_003: [**STRING_TOKENIZER_create_from_char shall return an NULL STRING_TOKENIZER _HANDLE on any error that is encountered**]**
**SRS_STRING_TOKENIZER_07_001: [** STRING_TOKENIZER_create_from_char shall return an NULL STRING_TOKENIZER_HANDLE if parameter input is NULL **]**
### STRING_TOKENIZER_get_next_token
extern int STRING_TOKENIZER_get_next_token(STRING_TOKENIZER_HANDLE t, STRING_HANDLE output,const char* delimiters);
**SRS_STRING_TOKENIZER_04_004: [**STRING_TOKENIZER_get_next_token shall return a nonzero value if any of the 3 parameters is NULL**]**
**SRS_STRING_TOKENIZER_04_005: [**STRING_TOKENIZER_get_next_token searches the string inside STRING_TOKENIZER_HANDLE for the first character that is NOT contained in the current delimiter**]**
**SRS_STRING_TOKENIZER_04_006: [**If no such character is found, then STRING_TOKENIZER_get_next_token shall return a nonzero Value (You've reach the end of the string or the string consists with only delimiterstokens).**]**
**SRS_STRING_TOKENIZER_04_007: [**If such a character is found, STRING_TOKENIZER_get_next_token shall consider it as the start of a token.**]**
**SRS_STRING_TOKENIZER_04_008: [**STRING_TOKENIZER_get_next_token than searches from the start of a token for a character that is contained in the delimiters string.**]**
**SRS_STRING_TOKENIZER_04_009: [**If no such character is found, STRING_TOKENIZER_get_next_token extends the current token to the end of the string inside t, copies the token to output and returns 0.**]**
**SRS_STRING_TOKENIZER_04_010: [**If such a character is found, STRING_TOKENIZER_get_next_token shall consider it the end of the token and copy its content to output, updates the current position inside t to the next character and returns 0.**]**
**SRS_STRING_TOKENIZER_04_011: [**Each subsequent call to STRING_TOKENIZER_get_next_token starts searching from the saved position on t and behaves as described above.**]**
**SRS_STRING_TOKENIZER_TOKENIZER_04_014: [**STRING_TOKENIZER_get_next_token shall return nonzero value if t contains an empty string.**]**
**SRS_STRING_TOKENIZER_07_002: [** STRING_TOKENIZER_create_from_char shall allocate a new STRING_TOKENIZER _HANDLE having the content of the STRING_HANDLE copied and current position pointing at the beginning of the string **]**
### STRING_TOKENIZER_destroy
**SRS_STRING_TOKENIZER_07_003: [** STRING_TOKENIZER_create_from_char shall return an NULL STRING_TOKENIZER _HANDLE on any error that is encountered **]**
### STRING_TOKENIZER_get_next_token
extern int STRING_TOKENIZER_get_next_token(STRING_TOKENIZER_HANDLE t, STRING_HANDLE output,const char* delimiters);
**SRS_STRING_TOKENIZER_04_004: [** STRING_TOKENIZER_get_next_token shall return a nonzero value if any of the 3 parameters is NULL **]**
**SRS_STRING_TOKENIZER_04_005: [** STRING_TOKENIZER_get_next_token searches the string inside STRING_TOKENIZER_HANDLE for the first character that is NOT contained in the current delimiter **]**
**SRS_STRING_TOKENIZER_04_006: [** If no such character is found, then STRING_TOKENIZER_get_next_token shall return a nonzero Value (You've reach the end of the string or the string consists with only delimiterstokens). **]**
**SRS_STRING_TOKENIZER_04_007: [** If such a character is found, STRING_TOKENIZER_get_next_token shall consider it as the start of a token. **]**
**SRS_STRING_TOKENIZER_04_008: [** STRING_TOKENIZER_get_next_token than searches from the start of a token for a character that is contained in the delimiters string. **]**
**SRS_STRING_TOKENIZER_04_009: [** If no such character is found, STRING_TOKENIZER_get_next_token extends the current token to the end of the string inside t, copies the token to output and returns 0. **]**
**SRS_STRING_TOKENIZER_04_010: [** If such a character is found, STRING_TOKENIZER_get_next_token shall consider it the end of the token and copy its content to output, updates the current position inside t to the next character and returns 0. **]**
**SRS_STRING_TOKENIZER_04_011: [** Each subsequent call to STRING_TOKENIZER_get_next_token starts searching from the saved position on t and behaves as described above. **]**
**SRS_STRING_TOKENIZER_TOKENIZER_04_014: [** STRING_TOKENIZER_get_next_token shall return nonzero value if t contains an empty string. **]**
### STRING_TOKENIZER_destroy
extern void STRING_TOKENIZER_destroy(STRING_TOKENIZER_HANDLE t);
**SRS_STRING_TOKENIZER_TOKENIZER_04_012: [**STRING_TOKENIZER_destroy shall free the memory allocated by the STRING_TOKENIZER_create **]**
**SRS_STRING_TOKENIZER_TOKENIZER_04_013: [**When the t argument is NULL, then STRING_TOKENIZER_destroy shall not attempt to free**]**
**SRS_STRING_TOKENIZER_TOKENIZER_04_012: [** STRING_TOKENIZER_destroy shall free the memory allocated by the STRING_TOKENIZER_create **]**
**SRS_STRING_TOKENIZER_TOKENIZER_04_013: [** When the t argument is NULL, then STRING_TOKENIZER_destroy shall not attempt to free **]**

232
devdoc/strings_requirements.md
Просмотреть файл

@ -1,17 +1,17 @@
strings requirements
================
##Overview
## Overview
The STRING object encapsulates a char* variable. This interface is access by STRING_HANDLE variables that provide further encapsulation of the interface.
##Exposed API
## Exposed API
```c
typedef void* STRING_HANDLE;
typedef void* STRING_HANDLE;
extern STRING_HANDLE STRING_new(void);
extern STRING_HANDLE STRING_clone(STRING_HANDLE handle);
extern STRING_HANDLE STRING_construct(const char* psz);
@ -35,172 +35,211 @@ extern int STRING_sprintf(STRING_HANDLE s1, const char* format, ...);
```
###STRING_new
### STRING_new
```c
extern STRING_HANDLE STRING_new(void);
```
**SRS_STRING_07_001: [**STRING_new shall allocate a new STRING_HANDLE pointing to an empty string.**]**
**SRS_STRING_07_002: [**STRING_new shall return an NULL STRING_HANDLE on any error that is encountered.**]**
**SRS_STRING_07_001: [** STRING_new shall allocate a new STRING_HANDLE pointing to an empty string. **]**
###STRING_clone
**SRS_STRING_07_002: [** STRING_new shall return an NULL STRING_HANDLE on any error that is encountered. **]**
### STRING_clone
```c
extern STRING_HANDLE STRING_clone(STRING_HANDLE handle);
```
**SRS_STRING_02_001: [**STRING_clone shall produce a new string having the same content as the handle string.**]**
**SRS_STRING_02_002: [**If parameter handle is NULL then STRING_clone shall return NULL.**]**
**SRS_STRING_02_003: [**If STRING_clone fails for any reason, it shall return NULL.**]**
**SRS_STRING_02_001: [** STRING_clone shall produce a new string having the same content as the handle string. **]**
###STRING_construct
**SRS_STRING_02_002: [** If parameter handle is NULL then STRING_clone shall return NULL. **]**
**SRS_STRING_02_003: [** If STRING_clone fails for any reason, it shall return NULL. **]**
### STRING_construct
```c
extern STRING_HANDLE STRING_construct(const char*)
```
**SRS_STRING_07_003: [**STRING_construct shall allocate a new string with the value of the specified const char*.**]**
**SRS_STRING_07_005: [**If the supplied const char* is NULL STRING_construct shall return a NULL value.**]**
**SRS_STRING_07_032: [**STRING_construct encounters any error it shall return a NULL value.**]**
**SRS_STRING_07_003: [** STRING_construct shall allocate a new string with the value of the specified const char*. **]**
###STRING_new_with_memory
**SRS_STRING_07_005: [** If the supplied const char* is NULL STRING_construct shall return a NULL value. **]**
**SRS_STRING_07_032: [** STRING_construct encounters any error it shall return a NULL value. **]**
### STRING_new_with_memory
```c
extern STRING_HANDLE STRING_new_with_memory(char*)
```
**SRS_STRING_07_006: [**STRING_new_with_memory shall return a STRING_HANDLE by using the supplied char* memory.**]**
**SRS_STRING_07_007: [**STRING_new_with_memory shall return a NULL STRING_HANDLE if the supplied char* is NULL.**]**
**SRS_STRING_07_006: [** STRING_new_with_memory shall return a STRING_HANDLE by using the supplied char* memory. **]**
###STRING_new_quoted
**SRS_STRING_07_007: [** STRING_new_with_memory shall return a NULL STRING_HANDLE if the supplied char* is NULL. **]**
### STRING_new_quoted
```c
extern STRING_HANDLE STRING_new_quoted(const char*)
```
**SRS_STRING_07_008: [**STRING_new_quoted shall return a valid STRING_HANDLE Copying the supplied const char* value surrounded by quotes.**]**
**SRS_STRING_07_009: [**STRING_new_quoted shall return a NULL STRING_HANDLE if the supplied const char* is NULL.**]**
**SRS_STRING_07_031: [**STRING_new_quoted shall return a NULL STRING_HANDLE if any error is encountered.**]**
**SRS_STRING_07_008: [** STRING_new_quoted shall return a valid STRING_HANDLE Copying the supplied const char* value surrounded by quotes. **]**
###STRING_new_JSON
**SRS_STRING_07_009: [** STRING_new_quoted shall return a NULL STRING_HANDLE if the supplied const char* is NULL. **]**
**SRS_STRING_07_031: [** STRING_new_quoted shall return a NULL STRING_HANDLE if any error is encountered. **]**
### STRING_new_JSON
```c
extern STRING_HANDLE STRING_new_JSON(const char* source);
```
STRING_new_JSON produces a JSON value representation of the parameter passed as argument source.
**SRS_STRING_02_011: [**If source is NULL then STRING_new_JSON shall return NULL.**]**
STRING_new_JSON shall produce a STRING_HANDLE according to the following:
**SRS_STRING_02_012: [**The string shall begin with the quote character.**]**
**SRS_STRING_02_013: [**The string shall copy the characters of source "as they are" (until the '\0' character) with the following exceptions:**]**
**SRS_STRING_02_014: [**If any character has the value outside [1...127**]** then STRING_new_JSON shall fail and return NULL.]
**SRS_STRING_02_016: [**If the character is " (quote) then it shall be repsented as \".**]**
**SRS_STRING_02_017: [**If the character is \ (backslash) then it shall represented as \\.**]**
**SRS_STRING_02_018: [**If the character is / (slash) then it shall be represented as \/.**]**
**SRS_STRING_02_019: [**If the character code is less than 0x20 then it shall be represented as \u00xx, where xx is the hex representation of the character code.**]**
**SRS_STRING_02_020: [**The string shall end with " (quote).**]**
**SRS_STRING_02_021: [**If the complete JSON representation cannot be produced, then STRING_new_JSON shall fail and return NULL.**]**
###STRING_delete
**SRS_STRING_02_011: [** If source is NULL then STRING_new_JSON shall return NULL. **]**
STRING_new_JSON shall produce a STRING_HANDLE according to the following:
**SRS_STRING_02_012: [** The string shall begin with the quote character. **]**
**SRS_STRING_02_013: [** The string shall copy the characters of source "as they are" (until the '\0' character) with the following exceptions: **]**
**SRS_STRING_02_014: [** If any character has the value outside [1...127 **]** then STRING_new_JSON shall fail and return NULL.]
**SRS_STRING_02_016: [** If the character is " (quote) then it shall be repsented as \". **]**
**SRS_STRING_02_017: [** If the character is \ (backslash) then it shall represented as \\. **]**
**SRS_STRING_02_018: [** If the character is / (slash) then it shall be represented as \/. **]**
**SRS_STRING_02_019: [** If the character code is less than 0x20 then it shall be represented as \u00xx, where xx is the hex representation of the character code. **]**
**SRS_STRING_02_020: [** The string shall end with " (quote). **]**
**SRS_STRING_02_021: [** If the complete JSON representation cannot be produced, then STRING_new_JSON shall fail and return NULL. **]**
### STRING_delete
```c
extern void STRING_delete(STRING_HANDLE handle);
```
**SRS_STRING_07_010: [**STRING_delete will free the memory allocated by the STRING_HANDLE.**]**
**SRS_STRING_07_011: [**STRING_delete will not attempt to free anything with a NULL STRING_HANDLE.**]**
**SRS_STRING_07_010: [** STRING_delete will free the memory allocated by the STRING_HANDLE. **]**
###STRING_concat
**SRS_STRING_07_011: [** STRING_delete will not attempt to free anything with a NULL STRING_HANDLE. **]**
### STRING_concat
```c
extern int STRING_concat(STRING_HANDLE handle, const char* s2)
```
**SRS_STRING_07_012: [**STRING_concat shall concatenate the given STRING_HANDLE and the const char* value and place the value in the handle.**]**
**SRS_STRING_07_013: [**STRING_concat shall return a nonzero number if an error is encountered.**]**
**SRS_STRING_07_012: [** STRING_concat shall concatenate the given STRING_HANDLE and the const char* value and place the value in the handle. **]**
###STRING_concat
```c
**SRS_STRING_07_013: [** STRING_concat shall return a nonzero number if an error is encountered. **]**
### STRING_concat
```c
extern int STRING_concat(STRING_HANDLE handle, const char* s2)
```
**SRS_STRING_07_034: [**String_Concat_with_STRING shall concatenate a given STRING_HANDLE variable with a source STRING_HANDLE.**]**
**SRS_STRING_07_035: [**String_Concat_with_STRING shall return a nonzero number if an error is encountered.**]**
**SRS_STRING_07_034: [** String_Concat_with_STRING shall concatenate a given STRING_HANDLE variable with a source STRING_HANDLE. **]**
###STRING_quote
```c
**SRS_STRING_07_035: [** String_Concat_with_STRING shall return a nonzero number if an error is encountered. **]**
### STRING_quote
```c
extern int STRING_quote(STRING_HANDLE handle)
```
**SRS_STRING_07_014: [**STRING_quote shall "quote" the supplied STRING_HANDLE and return 0 on success.**]**
**SRS_STRING_07_015: [**STRING_quote shall return a nonzero value if any of the supplied parameters are NULL.**]**
**SRS_STRING_07_029: [**STRING_quote shall return a nonzero value if any error is encountered.**]**
**SRS_STRING_07_014: [** STRING_quote shall "quote" the supplied STRING_HANDLE and return 0 on success. **]**
###STRING_copy
```c
**SRS_STRING_07_015: [** STRING_quote shall return a nonzero value if any of the supplied parameters are NULL. **]**
**SRS_STRING_07_029: [** STRING_quote shall return a nonzero value if any error is encountered. **]**
### STRING_copy
```c
extern int STRING_copy(STRING_HANDLE s1, const char* s2)
```
**SRS_STRING_07_016: [**STRING_copy shall copy the const char* into the supplied STRING_HANDLE.**]**
**SRS_STRING_07_017: [**STRING_copy shall return a nonzero value if any of the supplied parameters are NULL.**]**
**SRS_STRING_07_027: [**STRING_copy shall return a nonzero value if any error is encountered.**]**
**SRS_STRING_07_026: [**If the underlying char* refered to by s1 handle is equal to char* s2 than STRING_copy shall be a noop and return 0.**]**
**SRS_STRING_07_033: [**If overlapping pointer address is given to STRING_copy the behavior is undefined.**]**
**SRS_STRING_07_016: [** STRING_copy shall copy the const char* into the supplied STRING_HANDLE. **]**
###STRING_copy_n
```c
**SRS_STRING_07_017: [** STRING_copy shall return a nonzero value if any of the supplied parameters are NULL. **]**
**SRS_STRING_07_027: [** STRING_copy shall return a nonzero value if any error is encountered. **]**
**SRS_STRING_07_026: [** If the underlying char* refered to by s1 handle is equal to char* s2 than STRING_copy shall be a noop and return 0. **]**
**SRS_STRING_07_033: [** If overlapping pointer address is given to STRING_copy the behavior is undefined. **]**
### STRING_copy_n
```c
extern int STRING_copy_n(STRING_HANDLE s1, const char* s2, size_t n)
```
**SRS_STRING_07_018: [**STRING_copy_n shall copy the number of characters in const char* or the size_t whichever is lesser.**]**
**SRS_STRING_07_019: [**STRING_copy_n shall return a nonzero value if STRING_HANDLE or const char* is NULL.**]**
**SRS_STRING_07_028: [**STRING_copy_n shall return a nonzero value if any error is encountered.**]**
**SRS_STRING_07_018: [** STRING_copy_n shall copy the number of characters in const char* or the size_t whichever is lesser. **]**
###STRING_c_str
```c
**SRS_STRING_07_019: [** STRING_copy_n shall return a nonzero value if STRING_HANDLE or const char* is NULL. **]**
**SRS_STRING_07_028: [** STRING_copy_n shall return a nonzero value if any error is encountered. **]**
### STRING_c_str
```c
extern const char* STRING_c_str(STRING_HANDLE handle)
```
**SRS_STRING_07_020: [**STRING_c_str shall return the const char* associated with the given STRING_HANDLE.**]**
**SRS_STRING_07_021: [**STRING_c_str shall return NULL if the STRING_HANDLE is NULL.**]**
**SRS_STRING_07_020: [** STRING_c_str shall return the const char* associated with the given STRING_HANDLE. **]**
### STRING_empty
**SRS_STRING_07_021: [** STRING_c_str shall return NULL if the STRING_HANDLE is NULL. **]**
### STRING_empty
```c
extern int STRING_empty(STRING_HANDLE s1)
```
**SRS_STRING_07_022: [**STRING_empty shall revert the STRING_HANDLE to an empty state.**]**
**SRS_STRING_07_023: [**STRING_empty shall return a nonzero value if the STRING_HANDLE is NULL.**]**
**SRS_STRING_07_030: [**STRING_empty shall return a nonzero value if the STRING_HANDLE is NULL.**]**
**SRS_STRING_07_022: [** STRING_empty shall revert the STRING_HANDLE to an empty state. **]**
###STRING_length
**SRS_STRING_07_023: [** STRING_empty shall return a nonzero value if the STRING_HANDLE is NULL. **]**
**SRS_STRING_07_030: [** STRING_empty shall return a nonzero value if the STRING_HANDLE is NULL. **]**
### STRING_length
```c
extern size_t STRING_length(STRING_HANDLE handle)
```
**SRS_STRING_07_024: [**STRING_length shall return the length of the underlying char* for the given handle**]**
**SRS_STRING_07_025: [**STRING_length shall return zero if the given handle is NULL.**]**
###STRING_construct_n
**SRS_STRING_07_024: [** STRING_length shall return the length of the underlying char* for the given handle **]**
**SRS_STRING_07_025: [** STRING_length shall return zero if the given handle is NULL. **]**
### STRING_construct_n
```c
extern STRING_HANDLE STRING_construct_n(const char* psz, size_t n);
```
**SRS_STRING_02_007: [**STRING_construct_n shall construct a STRING_HANDLE from first "n" characters of the string pointed to by psz parameter.**]**
**SRS_STRING_02_008: [**If psz is NULL then STRING_construct_n shall return NULL.**]**
**SRS_STRING_02_009: [**If n is bigger than the size of the string psz, then STRING_construct_n shall return NULL.**]**
**SRS_STRING_02_010: [**In all other error cases, STRING_construct_n shall return NULL.**]**
**SRS_STRING_02_007: [** STRING_construct_n shall construct a STRING_HANDLE from first "n" characters of the string pointed to by psz parameter. **]**
###STRING_compare
**SRS_STRING_02_008: [** If psz is NULL then STRING_construct_n shall return NULL. **]**
**SRS_STRING_02_009: [** If n is bigger than the size of the string psz, then STRING_construct_n shall return NULL. **]**
**SRS_STRING_02_010: [** In all other error cases, STRING_construct_n shall return NULL. **]**
### STRING_compare
```c
extern int STRING_compare(STRING_HANDLE h1, STRING_HANDLE h2);
```
**SRS_STRING_07_034: [**STRING_compare returns an integer greater than, equal to, or less than zero, accordingly as the string pointed to by s1 is greater than, equal to, or less than the string s2.**]**
**SRS_STRING_07_035: [**If h1 and h2 are both NULL then STRING_compare shall return 0.**]**
**SRS_STRING_07_036: [**If h1 is NULL and h2 is a nonNULL value then STRING_compare shall return 1.**]**
**SRS_STRING_07_037: [**If h2 is NULL and h1 is a nonNULL value then STRING_compare shall return -1.**]**
**SRS_STRING_07_038: [**STRING_compare shall compare the char s variable using the strcmp function.**]**
**SRS_STRING_07_034: [** STRING_compare returns an integer greater than, equal to, or less than zero, accordingly as the string pointed to by s1 is greater than, equal to, or less than the string s2. **]**
### STRING_from_byte_array
**SRS_STRING_07_035: [** If h1 and h2 are both NULL then STRING_compare shall return 0. **]**
**SRS_STRING_07_036: [** If h1 is NULL and h2 is a nonNULL value then STRING_compare shall return 1. **]**
**SRS_STRING_07_037: [** If h2 is NULL and h1 is a nonNULL value then STRING_compare shall return -1. **]**
**SRS_STRING_07_038: [** STRING_compare shall compare the char s variable using the strcmp function. **]**
### STRING_from_byte_array
```c
extern STRING_HANDLE STRING_from_byte_array(const unsigned char* source, size_t size)
```
STRING_from_BUFFER builds a string that has the same content (byte-by-byte) as a byte array.
STRING_from_BUFFER builds a string that has the same content (byte-by-byte) as a byte array.
**SRS_STRING_02_022: [** If `source` is NULL and size > 0 then `STRING_from_BUFFER` shall fail and return NULL. **]**
**SRS_STRING_02_023: [** Otherwise, `STRING_from_BUFFER` shall build a string that has the same content (byte-by-byte) as source and return a non-NULL handle. **]**
**SRS_STRING_02_024: [** If building the string fails, then `STRING_from_BUFFER` shall fail and return NULL. **]**
### STRING_construct_sprintf
### STRING_construct_sprintf
```c
extern STRING_HANDLE STRING_construct_sprintf(const char* format, ...);
@ -208,12 +247,15 @@ extern STRING_HANDLE STRING_construct_sprintf(const char* format, ...);
STRING_construct_sprintf constructs the STRING_HANDLE from a printf formatting
**SRS_STRING_07_039: [**If the parameter format is NULL then STRING_construct_sprintf shall return NULL.**]**
**SRS_STRING_07_040: [**If any error is encountered STRING_construct_sprintf shall return NULL.**]**
**SRS_STRING_07_041: [**STRING_construct_sprintf shall determine the size of the resulting string and allocate the necessary memory.**]**
**SRS_STRING_07_045: [**STRING_construct_sprintf shall allocate a new string with the value of the specified printf formated const char. **]**
**SRS_STRING_07_039: [** If the parameter format is NULL then STRING_construct_sprintf shall return NULL. **]**
### STRING_sprintf
**SRS_STRING_07_040: [** If any error is encountered STRING_construct_sprintf shall return NULL. **]**
**SRS_STRING_07_041: [** STRING_construct_sprintf shall determine the size of the resulting string and allocate the necessary memory. **]**
**SRS_STRING_07_045: [** STRING_construct_sprintf shall allocate a new string with the value of the specified printf formated const char. **]**
### STRING_sprintf
```c
extern int STRING_sprintf(STRING_HANDLE s1, const char* format, ...);
@ -221,6 +263,8 @@ extern int STRING_sprintf(STRING_HANDLE s1, const char* format, ...);
STRING_sprintf shall append a printf format style string to the end of a STRING_HANDLE.
**SRS_STRING_07_042: [**if the parameters s1 or format are NULL then STRING_sprintf shall return non zero value.**]**
**SRS_STRING_07_043: [**If any error is encountered STRING_sprintf shall return a non zero value.**]**
**SRS_STRING_07_044: [**On success STRING_sprintf shall return 0.**]**
**SRS_STRING_07_042: [** if the parameters s1 or format are NULL then STRING_sprintf shall return non zero value. **]**
**SRS_STRING_07_043: [** If any error is encountered STRING_sprintf shall return a non zero value. **]**
**SRS_STRING_07_044: [** On success STRING_sprintf shall return 0. **]**

31
devdoc/template_requirements.md
Просмотреть файл

@ -26,7 +26,7 @@ Add any reference that can support this implementation here. For example, it the
TARGET_RESULT_OUT_OF_MEMORY
DEFINE_ENUM(TARGET_RESULT, TARGET_RESULT_VALUES);
```
**]**
**]**
**SRS_TEMPLATE_21_012: [** The target shall implement the APIs defined in target.h:
```c
@ -34,37 +34,44 @@ TARGET_RESULT target_create(size_t size);
void target_destroy(void);
TARGET_RESULT target_foo(void);
```
**]**
**]**
### target_create
### target_create
```c
TARGET_RESULT target_create(size_t size);
```
**SRS_TEMPLATE_21_001: [** The target_create shall call callee_open to do stuff and allocate the memory. **]**
**SRS_TEMPLATE_21_002: [** If callee_open return error, the target_create shall return TARGET_RESULT_FAIL. **]**
**SRS_TEMPLATE_21_003: [** If there is no memory to control the target_create information, it shall return TARGET_RESULT_OUT_OF_MEMORY. **]**
**SRS_TEMPLATE_21_008: [** If callee_open got success, it shall return TARGET_RESULT_OK. **]**
**SRS_TEMPLATE_21_001: [** The target_create shall call callee_open to do stuff and allocate the memory. **]**
**SRS_TEMPLATE_21_002: [** If callee_open return error, the target_create shall return TARGET_RESULT_FAIL. **]**
**SRS_TEMPLATE_21_003: [** If there is no memory to control the target_create information, it shall return TARGET_RESULT_OUT_OF_MEMORY. **]**
**SRS_TEMPLATE_21_008: [** If callee_open got success, it shall return TARGET_RESULT_OK. **]**
**SRS_TEMPLATE_21_009: [** If callee_open is called but the connection is already created, it shall return TARGET_RESULT_OK. **]**
### target_destroy
### target_destroy
```c
void target_destroy(void);
```
**SRS_TEMPLATE_21_006: [** The target_destroy shall call callee_close to do stuff and free the memory. **]**
**SRS_TEMPLATE_21_006: [** The target_destroy shall call callee_close to do stuff and free the memory. **]**
**SRS_TEMPLATE_21_007: [** If target_destroy is called but the connection is not created, the target_destroy shall not do anything. **]**
### target_foo
### target_foo
```c
TARGET_RESULT target_foo(void);
```
**SRS_TEMPLATE_21_004: [** The target_foo shall do stuff calling callee_bar_1 and callee_bar_2. **]**
**SRS_TEMPLATE_21_005: [** If target_foo is called but the connection is not created, the target_foo shall return TARGET_RESULT_FAIL. **]**
**SRS_TEMPLATE_21_004: [** The target_foo shall do stuff calling callee_bar_1 and callee_bar_2. **]**
**SRS_TEMPLATE_21_005: [** If target_foo is called but the connection is not created, the target_foo shall return TARGET_RESULT_FAIL. **]**
**SRS_TEMPLATE_21_010: [** If target_foo cannot execute foo, the target_foo shall return TARGET_RESULT_FAIL. **]**

13
devdoc/threadapi_arduino_requirements.md
Просмотреть файл

@ -9,7 +9,7 @@ threadapi_arduino implements a wrapper function for Arduino's delay function. Ar
[Delay](https://www.arduino.cc/en/Reference/Delay)
### Exposed API
### Exposed API
**SRS_THREADAPI_ARDUINO_21_001: [** The threadapi_arduino shall implement the method sleep defined by the `threadapi.h`.
```c
@ -20,20 +20,21 @@ threadapi_arduino implements a wrapper function for Arduino's delay function. Ar
*/
MOCKABLE_FUNCTION(, void, ThreadAPI_Sleep, unsigned int, milliseconds);
```
**]**
**]**
### ThreadAPI_Sleep
### ThreadAPI_Sleep
```c
void ThreadAPI_Sleep(unsigned int milliseconds);
```
**SRS_THREADAPI_ARDUINO_21_002: [** The ThreadAPI_Sleep shall receive a time in milliseconds. **]**
**SRS_THREADAPI_ARDUINO_21_003: [** The ThreadAPI_Sleep shall stop the thread for the specified time. **]**
### ThreadAPI_Create
### ThreadAPI_Create
```c
THREADAPI_RESULT ThreadAPI_Create(THREAD_HANDLE* threadHandle, THREAD_START_FUNC func, void* arg);
@ -42,7 +43,7 @@ THREADAPI_RESULT ThreadAPI_Create(THREAD_HANDLE* threadHandle, THREAD_START_FUN
**SRS_THREADAPI_ARDUINO_21_004: [** The Arduino do not support ThreadAPI_Create, it shall return THREADAPI_ERROR. **]**
### ThreadAPI_Join
### ThreadAPI_Join
```c
THREADAPI_RESULT ThreadAPI_Join(THREAD_HANDLE threadHandle, int* res);
@ -51,7 +52,7 @@ THREADAPI_RESULT ThreadAPI_Join(THREAD_HANDLE threadHandle, int* res);
**SRS_THREADAPI_ARDUINO_21_005: [** The Arduino do not support ThreadAPI_Join, it shall return THREADAPI_ERROR. **]**
### ThreadAPI_Exit
### ThreadAPI_Exit
```c
void ThreadAPI_Exit(int res);

15
devdoc/threadapi_freertos_requirements.md
Просмотреть файл

@ -9,7 +9,7 @@ threadapi_freertos implements a wrapper function for the FreeRTOS `vTaskDelay` f
[vTaskDelay](http://www.freertos.org/a00127.html)
### Exposed API
### Exposed API
**SRS_THREADAPI_FREERTOS_30_001: [** The threadapi_freertos shall implement the method `ThreadAPI_Sleep` defined in `threadapi.h`.
```c
@ -20,20 +20,21 @@ threadapi_freertos implements a wrapper function for the FreeRTOS `vTaskDelay` f
*/
void ThreadAPI_Sleep(unsigned int milliseconds);
```
**]**
**]**
### ThreadAPI_Sleep
### ThreadAPI_Sleep
```c
void ThreadAPI_Sleep(unsigned int milliseconds);
```
**SRS_THREADAPI_FREERTOS_30_002: [** The ThreadAPI_Sleep shall receive a time in milliseconds. **]**
**SRS_THREADAPI_FREERTOS_30_002: [** The ThreadAPI_Sleep shall receive a time in milliseconds. **]**
**SRS_THREADAPI_FREERTOS_30_003: [** The ThreadAPI_Sleep shall stop the thread for the specified time. **]**
### ThreadAPI_Create
### ThreadAPI_Create
```c
THREADAPI_RESULT ThreadAPI_Create(THREAD_HANDLE* threadHandle, THREAD_START_FUNC func, void* arg);
@ -42,7 +43,7 @@ THREADAPI_RESULT ThreadAPI_Create(THREAD_HANDLE* threadHandle, THREAD_START_FUN
**SRS_THREADAPI_FREERTOS_30_004: [** FreeRTOS is not guaranteed to support threading, so ThreadAPI_Create shall return THREADAPI_ERROR. **]**
### ThreadAPI_Join
### ThreadAPI_Join
```c
THREADAPI_RESULT ThreadAPI_Join(THREAD_HANDLE threadHandle, int* res);
@ -51,7 +52,7 @@ THREADAPI_RESULT ThreadAPI_Join(THREAD_HANDLE threadHandle, int* res);
**SRS_THREADAPI_FREERTOS_30_005: [** FreeRTOS is not guaranteed to support threading, so ThreadAPI_Join shall return THREADAPI_ERROR. **]**
### ThreadAPI_Exit
### ThreadAPI_Exit
```c
void ThreadAPI_Exit(int res);

25
devdoc/tickcounter_freertos_requirement.md
Просмотреть файл

@ -25,7 +25,7 @@ typedef uint_fast32_t tickcounter_ms_t;
// TICK_COUNTER_INSTANCE_TAG* is an opaque handle type
typedef struct TICK_COUNTER_INSTANCE_TAG* TICK_COUNTER_HANDLE;
```
**]**
**]**
**SRS_TICKCOUNTER_FREERTOS_30_002: [** The tickcounter_freertos adapter shall implement the API calls defined in tickcounter.h:
```c
@ -33,36 +33,41 @@ TICK_COUNTER_HANDLE tickcounter_create(void);
void tickcounter_destroy(TICK_COUNTER_HANDLE tick_counter);
int tickcounter_get_current_ms(TICK_COUNTER_HANDLE tick_counter, tickcounter_ms_t* current_ms);
```
**]**
**]**
### tickcounter_create
### tickcounter_create
The `tickcounter_create` call allocates and initializes an internally defined TICK_COUNTER_INSTANCE structure and returns its pointer as type TICK_COUNTER_HANDLE.
```c
TICK_COUNTER_HANDLE tickcounter_create(void);
```
**SRS_TICKCOUNTER_FREERTOS_30_003: [** `tickcounter_create` shall allocate and initialize an internally-defined TICK_COUNTER_INSTANCE structure and return its pointer on success. **]**
**SRS_TICKCOUNTER_FREERTOS_30_003: [** `tickcounter_create` shall allocate and initialize an internally-defined TICK_COUNTER_INSTANCE structure and return its pointer on success. **]**
**SRS_TICKCOUNTER_FREERTOS_30_004: [** If allocation of the internally-defined TICK_COUNTER_INSTANCE structure fails, `tickcounter_create` shall return NULL. (Initialization failure is not possible for FreeRTOS.) **]**
### tickcounter_destroy
### tickcounter_destroy
The `tickcounter_destroy` call releases all resources acquired by the `tickcounter_create` call.
```c
void tickcounter_destroy(TICK_COUNTER_HANDLE tick_counter);
```
**SRS_TICKCOUNTER_FREERTOS_30_005: [** `tickcounter_destroy` shall delete the internally-defined TICK_COUNTER_INSTANCE structure specified by the `tick_counter` parameter. (This call has no failure case.) **]**
**SRS_TICKCOUNTER_FREERTOS_30_005: [** `tickcounter_destroy` shall delete the internally-defined TICK_COUNTER_INSTANCE structure specified by the `tick_counter` parameter. (This call has no failure case.) **]**
**SRS_TICKCOUNTER_FREERTOS_30_006: [** If the `tick_counter` parameter is NULL, `tickcounter_destroy` shall do nothing. **]**
### tickcounter_get_current_ms
### tickcounter_get_current_ms
The `tickcounter_get_current_ms` call returns the number of milleconds elapsed since the `tickcounter_create` call.
```c
int tickcounter_get_current_ms(TICK_COUNTER_HANDLE tick_counter, tickcounter_ms_t* current_ms);
```
**SRS_TICKCOUNTER_FREERTOS_30_007: [** If the `tick_counter` parameter is NULL, `tickcounter_get_current_ms` shall return a non-zero value to indicate error. **]**
**SRS_TICKCOUNTER_FREERTOS_30_008: [** If the `current_ms` parameter is NULL, `tickcounter_get_current_ms` shall return a non-zero value to indicate error. **]**
**SRS_TICKCOUNTER_FREERTOS_30_009: [** `tickcounter_get_current_ms` shall set `*current_ms` to the number of milliseconds elapsed since the `tickcounter_create` call for the specified `tick_counter` and return 0 to indicate success (In FreeRTOS this call has no failure case.) **]**
**SRS_TICKCOUNTER_FREERTOS_30_007: [** If the `tick_counter` parameter is NULL, `tickcounter_get_current_ms` shall return a non-zero value to indicate error. **]**
**SRS_TICKCOUNTER_FREERTOS_30_008: [** If the `current_ms` parameter is NULL, `tickcounter_get_current_ms` shall return a non-zero value to indicate error. **]**
**SRS_TICKCOUNTER_FREERTOS_30_009: [** `tickcounter_get_current_ms` shall set `*current_ms` to the number of milliseconds elapsed since the `tickcounter_create` call for the specified `tick_counter` and return 0 to indicate success (In FreeRTOS this call has no failure case.) **]**
**SRS_TICKCOUNTER_FREERTOS_30_010: [** If the FreeRTOS call `xTaskGetTickCount` experiences a single overflow between the calls to `tickcounter_create` and `tickcounter_get_current_ms`, the `tickcounter_get_current_ms` call shall still return the correct interval. **]**

28
devdoc/tlsio_arduino_requirements.md
Просмотреть файл

@ -40,7 +40,7 @@ typedef struct IO_INTERFACE_DESCRIPTION_TAG
IO_SETOPTION concrete_io_setoption;
} IO_INTERFACE_DESCRIPTION;
```
**]**
**]**
**SRS_TLSIO_ARDUINO_21_002: [** The tlsio_arduino shall report the open operation status using the IO_OPEN_RESULT enumerator defined in the `xio.h`:
```c
@ -51,7 +51,7 @@ typedef enum IO_OPEN_RESULT_TAG
IO_OPEN_CANCELLED
} IO_OPEN_RESULT;
```
**]**
**]**
**SRS_TLSIO_ARDUINO_21_003: [** The tlsio_arduino shall report the send operation status using the IO_SEND_RESULT enumerator defined in the `xio.h`:
```c
@ -62,7 +62,7 @@ typedef enum IO_SEND_RESULT_TAG
IO_SEND_CANCELLED
} IO_SEND_RESULT;
```
**]**
**]**
**SRS_TLSIO_ARDUINO_21_004: [** The tlsio_arduino shall call the callbacks functions defined in the `xio.h`:
```c
@ -72,7 +72,7 @@ typedef void(*ON_IO_OPEN_COMPLETE)(void* context, IO_OPEN_RESULT open_result);
typedef void(*ON_IO_CLOSE_COMPLETE)(void* context);
typedef void(*ON_IO_ERROR)(void* context);
```
**]**
**]**
**SRS_TLSIO_ARDUINO_21_005: [** The tlsio_arduino shall received the connection information using the TLSIO_CONFIG structure defined in `tlsio.h`:
```c
@ -82,7 +82,7 @@ typedef struct TLSIO_CONFIG_TAG
int port;
} TLSIO_CONFIG;
```
**]**
**]**
## Callbacks
@ -92,7 +92,7 @@ typedef struct TLSIO_CONFIG_TAG
**SRS_TLSIO_ARDUINO_21_007: [** If the callback function is set as NULL. The tlsio_arduino shall not call anything. **]**
### tlsio_arduino_get_interface_description
### tlsio_arduino_get_interface_description
```c
const IO_INTERFACE_DESCRIPTION* tlsio_arduino_get_interface_description(void);
```
@ -100,7 +100,7 @@ const IO_INTERFACE_DESCRIPTION* tlsio_arduino_get_interface_description(void);
**SRS_TLSIO_ARDUINO_21_008: [** The tlsio_arduino_get_interface_description shall return the VTable IO_INTERFACE_DESCRIPTION. **]**
### tlsio_arduino_create
### tlsio_arduino_create
Implementation of `IO_CREATE concrete_io_create`
```c
CONCRETE_IO_HANDLE tlsio_arduino_create(void* io_create_parameters);
@ -127,7 +127,7 @@ CONCRETE_IO_HANDLE tlsio_arduino_create(void* io_create_parameters);
**SRS_TLSIO_ARDUINO_21_020: [** If tlsio_arduino_create get success to create the tlsio instance, it shall set the tlsio state as TLSIO_ARDUINO_STATE_CLOSED. **]**
### tlsio_arduino_destroy
### tlsio_arduino_destroy
Implementation of `IO_DESTROY concrete_io_destroy`
```c
void tlsio_arduino_destroy(CONCRETE_IO_HANDLE tlsio_handle);
@ -142,7 +142,7 @@ void tlsio_arduino_destroy(CONCRETE_IO_HANDLE tlsio_handle);
**SRS_TLSIO_ARDUINO_21_025: [** If the tlsio state is TLSIO_ARDUINO_STATE_OPENING, TLSIO_ARDUINO_STATE_OPEN, or TLSIO_ARDUINO_STATE_CLOSING, the tlsio_arduino_destroy shall close destroy the tlsio, but log an error. **]**
### tlsio_arduino_open
### tlsio_arduino_open
Implementation of `IO_OPEN concrete_io_open`
```c
int tlsio_arduino_open(
@ -190,7 +190,7 @@ int tlsio_arduino_open(
**SRS_TLSIO_ARDUINO_21_042: [** If the tlsio_arduino_open retry to open more than 10 times without success, it shall call the on_io_open_complete with IO_OPEN_CANCELED. **]**
### tlsio_arduino_close
### tlsio_arduino_close
Implementation of `IO_CLOSE concrete_io_close`
```c
int tlsio_arduino_close(CONCRETE_IO_HANDLE tlsio_handle, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
@ -217,7 +217,7 @@ int tlsio_arduino_close(CONCRETE_IO_HANDLE tlsio_handle, ON_IO_CLOSE_COMPLETE on
**SRS_TLSIO_ARDUINO_21_051: [** If the tlsio_arduino_close retry to close more than 10 times without success, it shall call the on_io_error. **]**
### tlsio_arduino_send
### tlsio_arduino_send
Implementation of `IO_SEND concrete_io_send`
```c
int tlsio_arduino_send(CONCRETE_IO_HANDLE tlsio_handle, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context)
@ -244,7 +244,7 @@ int tlsio_arduino_send(CONCRETE_IO_HANDLE tlsio_handle, const void* buffer, size
**SRS_TLSIO_ARDUINO_21_061: [** If the size is 0, the tlsio_arduino_send shall not do anything, and return _LINE_. **]**
### tlsio_arduino_dowork
### tlsio_arduino_dowork
Implementation of `IO_DOWORK concrete_io_dowork`
```c
void tlsio_arduino_dowork(CONCRETE_IO_HANDLE tlsio_handle)
@ -281,7 +281,7 @@ void tlsio_arduino_dowork(CONCRETE_IO_HANDLE tlsio_handle)
**SRS_TLSIO_ARDUINO_21_076: [** The tlsio_arduino_dowork shall delete the buffer to store the data received from the ssl client. **]**
### tlsio_arduino_setoption
### tlsio_arduino_setoption
Implementation of `IO_SETOPTION concrete_io_setoption`
```c
int tlsio_arduino_setoption(CONCRETE_IO_HANDLE tlsio_handle, const char* optionName, const void* value)
@ -290,7 +290,7 @@ int tlsio_arduino_setoption(CONCRETE_IO_HANDLE tlsio_handle, const char* optionN
**SRS_TLSIO_ARDUINO_21_077: [** The tlsio_arduino_setoption shall not do anything, and return 0. **]**
### tlsio_arduino_retrieveoptions
### tlsio_arduino_retrieveoptions
Implementation of `IO_RETRIEVEOPTIONS concrete_io_retrieveoptions`
```c
OPTIONHANDLER_HANDLE tlsio_arduino_retrieveoptions(CONCRETE_IO_HANDLE tlsio_handle)

95
devdoc/tlsio_cyclonessl_requirements.md
Просмотреть файл

@ -19,7 +19,7 @@ MOCKABLE_FUNCTION(, const IO_INTERFACE_DESCRIPTION*, tlsio_cyclonessl_get_interf
```
### tlsio_cyclonessl_create
### tlsio_cyclonessl_create
tlsio_cyclonessl_create is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_create member.
@ -28,26 +28,44 @@ CONCRETE_IO_HANDLE tlsio_cyclonessl_create(void* io_create_parameters);
```
**SRS_TLSIO_CYCLONESSL_01_001: [** tlsio_cyclonessl_create shall create a new instance of the tlsio for Cyclone SSL. **]**
**SRS_TLSIO_CYCLONESSL_01_002: [** If io_create_parameters is NULL, tlsio_cyclonessl_create shall fail and return NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_003: [** io_create_parameters shall be used as a TLSIO_CONFIG\*. **]**
**SRS_TLSIO_CYCLONESSL_01_004: [** If the hostname member is NULL, then tlsio_cyclonessl_create shall fail and return NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_005: [** tlsio_cyclonessl_create shall copy the hostname and port values for later use when the open of the underlying socket is needed. **]**
**SRS_TLSIO_CYCLONESSL_01_006: [** hostname shall be copied by calling mallocAndStrcpy_s. **]**
**SRS_TLSIO_CYCLONESSL_01_076: [** If allocating memory for the TLS IO instance fails then tlsio_cyclonessl_create shall fail and return NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_007: [** If mallocAndStrcpy_s fails then tlsio_cyclonessl_create shall fail and return NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_008: [** tlsio_cyclonessl_create shall initialize the yarrow context by calling yarrowInit. **]**
**SRS_TLSIO_CYCLONESSL_01_009: [** If yarrowInit fails then tlsio_cyclonessl_create shall return NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_010: [** The yarrow context shall be seeded with 32 bytes of randomly chosen data by calling yarrowSeed. **]**
**SRS_TLSIO_CYCLONESSL_01_011: [** If yarrowSeed fails then tlsio_cyclonessl_create shall return NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_012: [** tlsio_cyclonessl_create shall create a TLS context by calling tlsInit. **]**
**SRS_TLSIO_CYCLONESSL_01_013: [** If tlsInit fails then tlsio_cyclonessl_create shall return NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_014: [** The TLS context shall be setup to operate as a client by calling tlsSetConnectionEnd with TLS_CONNECTION_END_CLIENT. **]**
**SRS_TLSIO_CYCLONESSL_01_015: [** If tlsSetConnectionEnd fails then tlsio_cyclonessl_create shall return NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_016: [** The pseudo random number generator to be used shall be set by calling tlsSetPrng with the yarrow instance as argument. **]**
**SRS_TLSIO_CYCLONESSL_01_016: [** The pseudo random number generator to be used shall be set by calling tlsSetPrng with the yarrow instance as argument. **]**
**SRS_TLSIO_CYCLONESSL_01_017: [** If tlsSetPrng fails then tlsio_cyclonessl_create shall return NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_018: [** When tlsio_cyclonessl_create fails, all allocated resources up to that point shall be freed. **]**
### tlsio_cyclonessl_destroy
### tlsio_cyclonessl_destroy
tlsio_cyclonessl_destroy is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_destroy member.
@ -56,13 +74,18 @@ void tlsio_cyclonessl_destroy(CONCRETE_IO_HANDLE tls_io);
```
**SRS_TLSIO_CYCLONESSL_01_019: [** tlsio_cyclonessl_destroy shall free the tlsio CycloneSSL instance. **]**
**SRS_TLSIO_CYCLONESSL_01_020: [** If tls_io is NULL, tlsio_cyclonessl_destroy shall do nothing. **]**
**SRS_TLSIO_CYCLONESSL_01_021: [** tlsio_cyclonessl_destroy shall deinitialize the yarrow context by calling yarrowRelease. **]**
**SRS_TLSIO_CYCLONESSL_01_022: [** The TLS context shall be freed by calling tlsFree. **]**
**SRS_TLSIO_CYCLONESSL_01_077: [** All options cached via tlsio_cyclonessl_set_option shall also be freed. **]**
**SRS_TLSIO_CYCLONESSL_01_081: [** tlsio_cyclonessl_destroy should close the IO if it was open before freeing all the resources. **]**
### tlsio_cyclonessl_open
### tlsio_cyclonessl_open
tlsio_cyclonessl_open is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_open member.
@ -71,19 +94,30 @@ int tlsio_cyclonessl_open(CONCRETE_IO_HANDLE tls_io, ON_IO_OPEN_COMPLETE on_io_o
```
**SRS_TLSIO_CYCLONESSL_01_023: [** tlsio_cyclonessl_open shall open the TLS io and on success it shall return 0. **]**
**SRS_TLSIO_CYCLONESSL_01_024: [** If any of the arguments tls_io, on_io_open_complete, on_bytes_received or on_io_error are NULL then tlsio_cyclonessl_open shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_024: [** If any of the arguments tls_io, on_io_open_complete, on_bytes_received or on_io_error are NULL then tlsio_cyclonessl_open shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_025: [** tlsio_cyclonessl_open shall create a socket by calling tlsio_cyclonessl_socket_create, while passing to it the hostname and port that were saved in the tlsio_cyclonessl_create. **]**
**SRS_TLSIO_CYCLONESSL_01_026: [** If tlsio_cyclonessl_socket_create fails, then tlsio_cyclonessl_open shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_027: [** The socket created by tlsio_cyclonessl_socket_create shall be assigned to the TLS context by calling tlsSetSocket. **]**
**SRS_TLSIO_CYCLONESSL_01_028: [** If tlsSetSocket fails then tlsio_cyclonessl_open shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_078: [** If certificates have been set by using tlsio_cyclonessl_set_option then a call to tlsSetTrustedCaList shall be made to pass the certificates to CycloneSSL. **]**
**SRS_TLSIO_CYCLONESSL_01_079: [** If tlsSetTrustedCaList fails then tlsio_cyclonessl_open shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_079: [** If tlsSetTrustedCaList fails then tlsio_cyclonessl_open shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_031: [** tlsio_cyclonessl_open shall start the TLS handshake by calling tlsConnect. **]**
**SRS_TLSIO_CYCLONESSL_01_032: [** If tlsConnect fails then tlsio_cyclonessl_open shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_033: [** If tlsConnect succeeds, the callback on_io_open_complete shall be called, while passing on_io_open_complete_context and IO_OPEN_OK as arguments. **]**
**SRS_TLSIO_CYCLONESSL_01_034: [** If tlsio_cyclonessl_open is called while the IO is open, tlsio_cyclonessl_open shall fail and return a non-zero value without performing any work to open the IO. **]**
### tlsio_cyclonessl_close
### tlsio_cyclonessl_close
tlsio_cyclonessl_close is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_close member.
@ -92,14 +126,20 @@ int tlsio_cyclonessl_close(CONCRETE_IO_HANDLE tls_io, ON_IO_CLOSE_COMPLETE on_io
```
**SRS_TLSIO_CYCLONESSL_01_035: [** tlsio_cyclonessl_close shall close the TLS IO and on success it shall return 0. **]**
**SRS_TLSIO_CYCLONESSL_01_036: [** If the argument tls_io is NULL, tlsio_cyclonessl_close shall fail and return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_037: [** tlsio_cyclonessl_close shall close the TLS connection by calling tlsShutdown. **]**
**SRS_TLSIO_CYCLONESSL_01_038: [** If tlsShutdown fails, tlsio_cyclonessl_close shall fail and return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_039: [** tlsio_cyclonessl_destroy shall destroy the underlying socket by calling tlsio_cyclonessl_socket_destroy. **]**
**SRS_TLSIO_CYCLONESSL_01_040: [** On success, on_io_close_complete shall be called while passing as argument on_io_close_complete_context. **]**
**SRS_TLSIO_CYCLONESSL_01_041: [** If tlsio_cyclonessl_close is called when not open, tlsio_cyclonessl_close shall fail and return a non-zero value. **]**
### tlsio_cyclonessl_send
### tlsio_cyclonessl_send
tlsio_cyclonessl_send is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_send member.
@ -108,15 +148,22 @@ int tlsio_cyclonessl_send(CONCRETE_IO_HANDLE tls_io, const void* buffer, size_t
```
**SRS_TLSIO_CYCLONESSL_01_042: [** tlsio_cyclonessl_send shall send the `size` bytes pointed to by `buffer` and on success it shall return 0. **]**
**SRS_TLSIO_CYCLONESSL_01_043: [** If any of the arguments tls_io or buffer is NULL, tlsio_cyclonessl_send shall fail and return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_044: [** If size is 0, tlsio_cyclonessl_send shall fail and return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_045: [** on_send_complete shall be allowed to be NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_046: [** On success, if a non-NULL value was passed for on_send_complete, then on_send_complete shall be called while passing to it the on_send_complete_context value. **]**
**SRS_TLSIO_CYCLONESSL_01_047: [** tlsio_cyclonessl_send shall send the bytes by calling tlsWrite and passing buffer and size as arguments. 0 shall be passed for the flags argument. **]**
**SRS_TLSIO_CYCLONESSL_01_048: [** If tlsio_cyclonessl_send is called when the IO is not open, tlsio_cyclonessl_send shall fail and return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_049: [** If the IO is in an error state (an error was reported through the on_io_error callback), tlsio_cyclonessl_send shall fail and return a non-zero value. **]**
### tlsio_cyclonessl_dowork
### tlsio_cyclonessl_dowork
tlsio_cyclonessl_dowork is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_dowork member.
@ -125,15 +172,22 @@ void tlsio_cyclonessl_dowork(CONCRETE_IO_HANDLE tls_io)
```
**SRS_TLSIO_CYCLONESSL_01_050: [** tlsio_cyclonessl_dowork shall check if any bytes are available to be read from the CycloneSSL library and indicate those bytes as received. **]**
**SRS_TLSIO_CYCLONESSL_01_051: [** If the tls_io argument is NULL, tlsio_cyclonessl_dowork shall do nothing. **]**
**SRS_TLSIO_CYCLONESSL_01_052: [** If the IO is not open (no open has been called or the IO has been closed) then tlsio_cyclonessl_dowork shall do nothing. **]**
**SRS_TLSIO_CYCLONESSL_01_052: [** If the IO is not open (no open has been called or the IO has been closed) then tlsio_cyclonessl_dowork shall do nothing. **]**
**SRS_TLSIO_CYCLONESSL_01_053: [** If the IO is open, tlsio_cyclonessl_dowork shall attempt to read 64 bytes from the TLS library by calling tlsRead. **]**
**SRS_TLSIO_CYCLONESSL_01_080: [** If any bytes are read from CycloneSSL they should be indicated via the on_bytes_received callback passed to tlsio_cyclonessl_open. **]**
**SRS_TLSIO_CYCLONESSL_01_054: [** The flags argument for tlsRead shall be 0. **]**
**SRS_TLSIO_CYCLONESSL_01_055: [** If tlsRead fails, the error shall be indicated by calling the on_io_error callback passed in tlsio_cyclonessl_open, while passing the on_io_error_context to the callback. **]**
**SRS_TLSIO_CYCLONESSL_01_056: [** Also the IO shall be considered in error and any subsequent calls to tlsio_cyclonessl_send shall fail. **]**
### tlsio_cyclonessl_setoption
### tlsio_cyclonessl_setoption
tlsio_cyclonessl_setoption is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_setoption member.
@ -142,17 +196,22 @@ int tlsio_cyclonessl_setoption(CONCRETE_IO_HANDLE tls_io, const char* optionName
```
**SRS_TLSIO_CYCLONESSL_01_057: [** If any of the arguments tls_io or option_name is NULL tlsio_cyclonessl_setoption shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_058: [** If the option_name argument indicates an option that is not handled by tlsio_cyclonessl, then tlsio_cyclonessl_setoption shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_059: [** If the option was handled by tlsio_cyclonessl, then tlsio_cyclonessl_setoption shall return 0. **]**
Options that shall be handled by tlsio_cyclonessl:
**SRS_TLSIO_CYCLONESSL_01_060: [** - "TrustedCerts" - a char\* that shall be saved by tlsio_cyclonessl as it shall be given to the underlying CycloneSSL TLS context when the IO is open. **]**
**SRS_TLSIO_CYCLONESSL_01_061: [** If copying the char\* passed in value fails then tlsio_cyclonessl_setoption shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_01_062: [** If a previous TrustedCerts option was saved, then the previous value shall be freed. **]**
**SRS_TLSIO_CYCLONESSL_01_063: [** A NULL value shall be allowed for TrustedCerts, in which case the previously stored TrustedCerts option value shall be cleared. **]**
### tlsio_cyclonessl_retrieve_options
### tlsio_cyclonessl_retrieve_options
tlsio_cyclonessl_retrieve_options is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_retrieveoptions member.
@ -163,12 +222,16 @@ static OPTIONHANDLER_HANDLE tlsio_cyclonessl_retrieve_options(CONCRETE_IO_HANDLE
tlsio_cyclonessl_retrieveoptions produces an OPTIONHANDLER_HANDLE.
**SRS_TLSIO_CYCLONESSL_01_064: [** If parameter handle is `NULL` then `tlsio_cyclonessl_retrieve_options` shall fail and return NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_065: [** `tlsio_cyclonessl_retrieve_options` shall produce an OPTIONHANDLER_HANDLE. **]**
**SRS_TLSIO_CYCLONESSL_01_066: [** `tlsio_cyclonessl_retrieve_options` shall add to it the options: **]**
**SRS_TLSIO_CYCLONESSL_01_067: [** - TrustedCerts **]**
**SRS_TLSIO_CYCLONESSL_01_068: [** If producing the OPTIONHANDLER_HANDLE fails then tlsio_cyclonessl_retrieve_options shall fail and return NULL. **]**
### tlsio_cyclonessl_get_interface_description
### tlsio_cyclonessl_get_interface_description
```c
extern const IO_INTERFACE_DESCRIPTION* tlsio_cyclonessl_get_interface_description(void);
@ -176,7 +239,7 @@ extern const IO_INTERFACE_DESCRIPTION* tlsio_cyclonessl_get_interface_descriptio
**SRS_TLSIO_CYCLONESSL_01_069: [** tlsio_cyclonessl_get_interface_description shall return a pointer to an IO_INTERFACE_DESCRIPTION structure that contains pointers to the functions: tlsio_cyclonessl_retrieve_options, tlsio_cyclonessl_create, tlsio_cyclonessl_destroy, tlsio_cyclonessl_open, tlsio_cyclonessl_close, tlsio_cyclonessl_send and tlsio_cyclonessl_dowork. **]**
### tlsio_cyclonessl_clone_option
### tlsio_cyclonessl_clone_option
tlsio_cyclonessl_clone_option is the implementation provided to the option handler instance created as part of tlsio_cyclonessl_retrieve_options.
@ -187,9 +250,10 @@ void* tlsio_cyclonessl_clone_option(const char* name, const void* value)
**SRS_TLSIO_CYCLONESSL_01_070: [** If the name or value arguments are NULL, tlsio_cyclonessl_clone_option shall return NULL. **]**
**SRS_TLSIO_CYCLONESSL_01_071: [** tlsio_cyclonessl_clone_option shall clone the option named `TrustedCerts` by calling mallocAndStrcpy_s. **]** **SRS_TLSIO_CYCLONESSL_01_072: [** On success it shall return a non-NULL pointer to the cloned option. **]**
**SRS_TLSIO_CYCLONESSL_01_073: [** If mallocAndStrcpy_s for `TrustedCerts` fails, tlsio_cyclonessl_clone_option shall return NULL. **]**
### tlsio_cyclonessl_destroy_option
### tlsio_cyclonessl_destroy_option
tlsio_cyclonessl_destroy_option is the implementation provided to the option handler instance created as part of tlsio_cyclonessl_retrieve_options.
@ -198,4 +262,5 @@ void tlsio_cyclonessl_destroy_option(const char* name, const void* value)
```
**SRS_TLSIO_CYCLONESSL_01_074: [** If any of the arguments is NULL, tlsio_cyclonessl_destroy_option shall do nothing. **]**
**SRS_TLSIO_CYCLONESSL_01_075: [** If the option name is `TrustedCerts`, tlsio_cyclonessl_destroy_option shall free the char\* option indicated by value. **]**

11
devdoc/tlsio_cyclonessl_socket_bsd_requirements.md
Просмотреть файл

@ -16,25 +16,32 @@ MOCKABLE_FUNCTION(, int, tlsio_cyclonessl_socket_create, const char*, hostname,
MOCKABLE_FUNCTION(, void, tlsio_cyclonessl_socket_destroy, TlsSocket, socket);
```
### tlsio_cyclonessl_socket_create
### tlsio_cyclonessl_socket_create
```c
int tlsio_cyclonessl_socket_create(const char* hostname, int port, TlsSocket* new_socket);
```
**SRS_TLSIO_CYCLONESSL_SOCKET_BSD_01_001: [** tlsio_cyclonessl_socket_create shall create a new socket to be used by CycloneSSL. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_BSD_01_008: [** On success tlsio_cyclonessl_socket_create shall return 0 and fill in the socket handle in the new_socket out argument. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_BSD_01_002: [** If hostname or new_socket is NULL, then tlsio_cyclonessl_socket_create shall fail and it shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_BSD_01_003: [** tlsio_cyclonessl_socket_create shall call socket to create a TCP socket. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_BSD_01_004: [** tlsio_cyclonessl_socket_create shall call getaddrinfo to obtain a hint ADDRINFO. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_BSD_01_006: [** tlsio_cyclonessl_socket_create shall call connect and pass the constructed address in order to connect the socket. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_BSD_01_007: [** If any of the socket calls fails, then tlsio_cyclonessl_socket_create shall fail and return a non-zero value. **]**
### tlsio_cyclonessl_socket_destroy
### tlsio_cyclonessl_socket_destroy
```c
void tlsio_cyclonessl_socket_destroy(TlsSocket socket)
```
**SRS_TLSIO_CYCLONESSL_SOCKET_BSD_01_009: [** tlsio_cyclonessl_socket_destroy shall close the socket passed as argument by calling the function close. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_BSD_01_010: [** If socket is INVALID_SOCKET (-1), tlsio_cyclonessl_socket_destroy shall do nothing. **]**

11
devdoc/tlsio_cyclonessl_socket_requirements.md
Просмотреть файл

@ -16,25 +16,32 @@ MOCKABLE_FUNCTION(, int, tlsio_cyclonessl_socket_create, const char*, hostname,
MOCKABLE_FUNCTION(, void, tlsio_cyclonessl_socket_destroy, TlsSocket, socket);
```
### tlsio_cyclonessl_socket_create
### tlsio_cyclonessl_socket_create
```c
int tlsio_cyclonessl_socket_create(const char* hostname, int port, TlsSocket* new_socket);
```
**SRS_TLSIO_CYCLONESSL_SOCKET_01_001: [** tlsio_cyclonessl_socket_create shall create a new socket to be used by CycloneSSL. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_01_002: [** On success tlsio_cyclonessl_socket_create shall return 0 and fill in the socket handle in the new_socket out argument. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_01_003: [** If hostname or socket is NULL, then tlsio_cyclonessl_socket_create shall fail and it shall return a non-zero value. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_01_004: [** tlsio_cyclonessl_socket_create shall call socketOpen to create a TCP socket. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_01_005: [** tlsio_cyclonessl_socket_create shall call getHostByName to obtain an IpAddr structure filled with the address of the hostname. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_01_006: [** tlsio_cyclonessl_socket_create shall call socketConnect and pass the obtained address in order to connect the socket. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_01_007: [** If any of the socket calls fails, then tlsio_cyclonessl_socket_create shall fail and return a non-zero value. **]**
### tlsio_cyclonessl_socket_destroy
### tlsio_cyclonessl_socket_destroy
```c
void tlsio_cyclonessl_socket_destroy(TlsSocket socket)
```
**SRS_TLSIO_CYCLONESSL_SOCKET_01_008: [** tlsio_cyclonessl_socket_destroy shall close the socket passed as argument by calling the function socketClose. **]**
**SRS_TLSIO_CYCLONESSL_SOCKET_01_009: [** If socket is NULL, tlsio_cyclonessl_socket_destroy shall do nothing. **]**

13
devdoc/uniqueid_requirements.md
Просмотреть файл

@ -15,11 +15,14 @@ The UniqueIDs module provides pseudo unique identifiers to the rest of the modul
extern UNIQUEID_RESULT UniqueId_Generate(char* uid, size_t bufferSize);
```
### UniqueId_Generate
### UniqueId_Generate
```C
extern UNIQUEID_RESULT UniqueId_Generate(char* uid, size_t len);
```
**SRS_UNIQUEID_07_001: [**UniqueId_Generate shall create a unique Id 36 character long string.**]**
**SRS_UNIQUEID_07_002: [**If uid is NULL then UniqueId_Generate shall return UNIQUEID_INVALID_ARG**]**
**SRS_UNIQUEID_07_003: [**If len is less then 37 then UniqueId_Generate shall return UNIQUEID_INVALID_ARG**]**
**SRS_UNIQUEID_07_004: [**If there is a failure for any reason the UniqueId_Generate shall return UNIQUEID_ERROR**]**
**SRS_UNIQUEID_07_001: [** UniqueId_Generate shall create a unique Id 36 character long string. **]**
**SRS_UNIQUEID_07_002: [** If uid is NULL then UniqueId_Generate shall return UNIQUEID_INVALID_ARG **]**
**SRS_UNIQUEID_07_003: [** If len is less then 37 then UniqueId_Generate shall return UNIQUEID_INVALID_ARG **]**
**SRS_UNIQUEID_07_004: [** If there is a failure for any reason the UniqueId_Generate shall return UNIQUEID_ERROR **]**

14
devdoc/url_encode_requirements.md
Просмотреть файл

@ -1,20 +1,22 @@
url_encode requirements
================
##Overview
## Overview
This document will specify the requirements for URL_Encode.
##Exposed API
## Exposed API
```c
extern STRING* URL_Encode(STRING* input);
```
###URL_Encode
### URL_Encode
URL_Encode will take as a parameter a pointer to a STRING, input. URL_Encode will return a pointer to STRING.
**SRS_URL_ENCODE_06_001: [**If input is NULL then URL_Encode will return NULL.**]**
**SRS_URL_ENCODE_06_002: [**If an error occurs during the encoding of input then URL_Encode will return NULL.**]**
**SRS_URL_ENCODE_06_003: [**If input is a zero length string then URL_Encode will return a zero length string.**]**
**SRS_URL_ENCODE_06_001: [** If input is NULL then URL_Encode will return NULL. **]**
**SRS_URL_ENCODE_06_002: [** If an error occurs during the encoding of input then URL_Encode will return NULL. **]**
**SRS_URL_ENCODE_06_003: [** If input is a zero length string then URL_Encode will return a zero length string. **]**
URL_Encode will encode input in a manner that respects the encoding used in the .net HttpUtility.UrlEncode.

28
devdoc/utf8_checker_requirements.md
Просмотреть файл

@ -1,5 +1,5 @@
# utf8_checker requirements
## Overview
utf8_checker is module that provides basic validation whether a string is a UTF-8 string.
@ -14,21 +14,27 @@ utf8_checker is module that provides basic validation whether a string is a UTF-
MOCKABLE_FUNCTION(, bool, utf8_checker_is_valid_utf8, const unsigned char*, utf8_str, size_t, length);
```
### utf8_checker_is_valid_utf8
### utf8_checker_is_valid_utf8
```c
extern bool utf8_checker_is_valid_utf8(const unsigned char* utf8_str, size_t length);
```
XX**SRS_UTF8_CHECKER_01_001: [** `utf8_checker_is_valid_utf8` shall verify that the sequence of chars pointed to by `utf8_str` represent UTF-8 encoded codepoints. **]**
XX**SRS_UTF8_CHECKER_01_005: [** On success it shall return true. **]**
XX**SRS_UTF8_CHECKER_01_002: [** If `utf8_checker_is_valid_utf8` is called with NULL `utf8_str` it shall return false. **]**
XX**SRS_UTF8_CHECKER_01_003: [** If `length` is 0, `utf8_checker_is_valid_utf8` shall consider `utf8_str` to be valid UTF-8 and return true. **]**
**SRS_UTF8_CHECKER_01_001: [** `utf8_checker_is_valid_utf8` shall verify that the sequence of chars pointed to by `utf8_str` represent UTF-8 encoded codepoints. **]**
### Relevant Unicode spec table
**SRS_UTF8_CHECKER_01_005: [** On success it shall return true. **]**
**SRS_UTF8_CHECKER_01_002: [** If `utf8_checker_is_valid_utf8` is called with NULL `utf8_str` it shall return false. **]**
**SRS_UTF8_CHECKER_01_003: [** If `length` is 0, `utf8_checker_is_valid_utf8` shall consider `utf8_str` to be valid UTF-8 and return true. **]**
### Relevant Unicode spec table
Scalar Value First Byte Second Byte Third Byte Fourth Byte
XX**SRS_UTF8_CHECKER_01_006: [** 00000000 0xxxxxxx 0xxxxxxx **]**
XX**SRS_UTF8_CHECKER_01_007: [** 00000yyy yyxxxxxx 110yyyyy 10xxxxxx **]**
XX**SRS_UTF8_CHECKER_01_008: [** zzzzyyyy yyxxxxxx 1110zzzz 10yyyyyy 10xxxxxx **]**
XX**SRS_UTF8_CHECKER_01_009: [** 000uuuuu zzzzyyyy yyxxxxxx 11110uuu 10uuzzzz 10yyyyyy 10xxxxxx **]**
**SRS_UTF8_CHECKER_01_006: [** 00000000 0xxxxxxx 0xxxxxxx **]**
**SRS_UTF8_CHECKER_01_007: [** 00000yyy yyxxxxxx 110yyyyy 10xxxxxx **]**
**SRS_UTF8_CHECKER_01_008: [** zzzzyyyy yyxxxxxx 1110zzzz 10yyyyyy 10xxxxxx **]**
**SRS_UTF8_CHECKER_01_009: [** 000uuuuu zzzzyyyy yyxxxxxx 11110uuu 10uuzzzz 10yyyyyy 10xxxxxx **]**

24
devdoc/uws_frame_encoder_requirements.md
Просмотреть файл

@ -1,5 +1,5 @@
# uws_frame_encoder requirements
## Overview
uws_frame_encoder is module that implements the WebSocket frame encoding rules.
@ -38,25 +38,35 @@ DEFINE_ENUM(WS_FRAME_TYPE, WS_FRAME_TYPE_VALUES);
extern int uws_frame_encoder_encode(BUFFER_HANDLE encode_buffer, WS_FRAME_TYPE opcode, const unsigned char* payload, size_t length, bool is_masked, bool is_final, unsigned char reserved);
```
### uws_create
### uws_create
```c
extern int uws_frame_encoder_encode(BUFFER_HANDLE encode_buffer, WS_FRAME_TYPE opcode, const unsigned char* payload, size_t length, bool is_masked, bool is_final, unsigned char reserved);
```
**SRS_UWS_FRAME_ENCODER_01_001: [** `uws_frame_encoder_encode` shall encode the information given in `opcode`, `payload`, `length`, `is_masked`, `is_final` and `reserved` according to the RFC6455 into a new buffer.**]**
**SRS_UWS_FRAME_ENCODER_01_001: [** `uws_frame_encoder_encode` shall encode the information given in `opcode`, `payload`, `length`, `is_masked`, `is_final` and `reserved` according to the RFC6455 into a new buffer. **]**
**SRS_UWS_FRAME_ENCODER_01_044: [** On success `uws_frame_encoder_encode` shall return a non-NULL handle to the result buffer. **]**
**SRS_UWS_FRAME_ENCODER_01_054: [** If `length` is greater than 0 and payload is NULL, then `uws_frame_encoder_encode` shall fail and return NULL. **]**
**SRS_UWS_FRAME_ENCODER_01_048: [** The newly created buffer shall be created by calling `BUFFER_new`. **]**
**SRS_UWS_FRAME_ENCODER_01_049: [** If `BUFFER_new` fails then `uws_frame_encoder_encode` shall fail and return NULL. **]**
**SRS_UWS_FRAME_ENCODER_01_046: [** The result buffer shall be resized accordingly using `BUFFER_enlarge`. **]**
**SRS_UWS_FRAME_ENCODER_01_047: [** If `BUFFER_enlarge` fails then `uws_frame_encoder_encode` shall fail and return NULL. **]**
**SRS_UWS_FRAME_ENCODER_01_050: [** The allocated memory shall be accessed by calling `BUFFER_u_char`. **]**
**SRS_UWS_FRAME_ENCODER_01_051: [** If `BUFFER_u_char` fails then `uws_frame_encoder_encode` shall fail and return a NULL. **]**
**SRS_UWS_FRAME_ENCODER_01_052: [** If `reserved` has any bits set except the lowest 3 then `uws_frame_encoder_encode` shall fail and return NULL. **]**
**SRS_UWS_FRAME_ENCODER_01_053: [** In order to obtain a 32 bit value for masking, `gb_rand` shall be used 4 times (for each byte). **]**
### RFC6455 relevant parts
### RFC6455 relevant parts
5. Data Framing
@ -260,16 +270,22 @@ extern int uws_frame_encoder_encode(BUFFER_HANDLE encode_buffer, WS_FRAME_TYPE o
**SRS_UWS_FRAME_ENCODER_01_033: [** A masked frame MUST have the field frame-masked set to 1, as defined in Section 5.2. **]**
**SRS_UWS_FRAME_ENCODER_01_034: [** The masking key is contained completely within the frame, as defined in Section 5.2 as frame-masking-key. **]**
**SRS_UWS_FRAME_ENCODER_01_035: [** It is used to mask the "Payload data" defined in the same section as frame-payload-data, which includes "Extension data" and "Application data". **]**
**SRS_UWS_FRAME_ENCODER_01_036: [** The masking key is a 32-bit value chosen at random by the client. **]**
**SRS_UWS_FRAME_ENCODER_01_037: [** When preparing a masked frame, the client MUST pick a fresh masking key from the set of allowed 32-bit values. **]**
**SRS_UWS_FRAME_ENCODER_01_038: [** The masking key needs to be unpredictable; thus, the masking key MUST be derived from a strong source of entropy, and the masking key for a given frame MUST NOT make it simple for a server/proxy to predict the masking key for a subsequent frame. **]**
The unpredictability of the masking key is essential to prevent authors of malicious applications from selecting the bytes that appear on the wire.
RFC 4086 [RFC4086] discusses what entails a suitable source of entropy for security-sensitive applications.
The masking does not affect the length of the "Payload data".
**SRS_UWS_FRAME_ENCODER_01_039: [** To convert masked data into unmasked data, or vice versa, the following algorithm is applied. **]**
**SRS_UWS_FRAME_ENCODER_01_040: [** The same algorithm applies regardless of the direction of the translation, e.g., the same steps are applied to mask the data as to unmask the data. **]**
**SRS_UWS_FRAME_ENCODER_01_041: [** Octet i of the transformed data ("transformed-octet-i") is the XOR of octet i of the original data ("original-octet-i") with octet at index i modulo 4 of the masking key ("masking-key-octet-j"): **]**

124
devdoc/vector_requirements.md
Просмотреть файл

@ -34,7 +34,7 @@ extern void* VECTOR_find_if(VECTOR_HANDLE handle, PREDICATE_FUNCTION pred, const
extern size_t VECTOR_size(VECTOR_HANDLE handle);
```
### PREDICATE_FUNCTION
### PREDICATE_FUNCTION
```c
bool(*PREDICATE_FUNCTION)(const void* element, const void* value);
/**
@ -52,110 +52,136 @@ bool(*PREDICATE_FUNCTION)(const void* element, const void* value);
```
### VECTOR_create
### VECTOR_create
```c
VECTOR_HANDLE VECTOR_create(size_t elementSize)
```
**SRS_VECTOR_10_001: [**VECTOR_create shall allocate a VECTOR_HANDLE that will contain an empty vector. The size of each element is given in elementSize.**]**
**SRS_VECTOR_10_002: [**VECTOR_create shall fail and return NULL if elementsize is equal to 0.**]**
**SRS_VECTOR_10_033: [**VECTOR_create shall fail and return NULL if malloc fails.**]**
**SRS_VECTOR_10_001: [** VECTOR_create shall allocate a VECTOR_HANDLE that will contain an empty vector. The size of each element is given in elementSize. **]**
### VECTOR_move
**SRS_VECTOR_10_002: [** VECTOR_create shall fail and return NULL if elementsize is equal to 0. **]**
**SRS_VECTOR_10_033: [** VECTOR_create shall fail and return NULL if malloc fails. **]**
### VECTOR_move
```c
VECTOR_HANDLE VECTOR_move(VECTOR_HANDLE handle)
```
**SRS_VECTOR_10_004: [**VECTOR_move shall allocate a VECTOR_HANLDE and move the data to it from the given handle.**]**
**SRS_VECTOR_10_005: [**VECTOR_move shall fail and return NULL if the given handle is NULL.**]**
**SRS_VECTOR_10_006: [**VECTOR_move shall fail and return NULL if malloc fails.**]**
**SRS_VECTOR_10_004: [** VECTOR_move shall allocate a VECTOR_HANLDE and move the data to it from the given handle. **]**
### VECTOR_destroy
**SRS_VECTOR_10_005: [** VECTOR_move shall fail and return NULL if the given handle is NULL. **]**
**SRS_VECTOR_10_006: [** VECTOR_move shall fail and return NULL if malloc fails. **]**
### VECTOR_destroy
```c
void VECTOR_destroy(VECTOR_HANDLE handle)
```
**SRS_VECTOR_10_008: [**VECTOR_destroy shall free the given handle and its internal storage.**]**
**SRS_VECTOR_10_009: [**VECTOR_destroy shall return if the given handle is NULL.**]**
**SRS_VECTOR_10_008: [** VECTOR_destroy shall free the given handle and its internal storage. **]**
### VECTOR_push_back
**SRS_VECTOR_10_009: [** VECTOR_destroy shall return if the given handle is NULL. **]**
### VECTOR_push_back
```c
int VECTOR_push_back(VECTOR_HANDLE handle, const void* elements, size_t numElements)
```
**SRS_VECTOR_10_011: [**VECTOR_push_back shall fail and return non-zero if `handle` is NULL.**]**
**SRS_VECTOR_10_034: [**VECTOR_push_back shall fail and return non-zero if `elements` is NULL.**]**
**SRS_VECTOR_10_035: [**VECTOR_push_back shall fail and return non-zero if `numElements` is 0.**]**
**SRS_VECTOR_10_012: [**VECTOR_push_back shall fail and return non-zero if memory allocation fails.**]**
**SRS_VECTOR_10_013: [**VECTOR_push_back shall append the given elements and return 0 indicating success.**]**
**SRS_VECTOR_10_011: [** VECTOR_push_back shall fail and return non-zero if `handle` is NULL. **]**
### VECTOR_erase
**SRS_VECTOR_10_034: [** VECTOR_push_back shall fail and return non-zero if `elements` is NULL. **]**
**SRS_VECTOR_10_035: [** VECTOR_push_back shall fail and return non-zero if `numElements` is 0. **]**
**SRS_VECTOR_10_012: [** VECTOR_push_back shall fail and return non-zero if memory allocation fails. **]**
**SRS_VECTOR_10_013: [** VECTOR_push_back shall append the given elements and return 0 indicating success. **]**
### VECTOR_erase
```c
void VECTOR_erase(VECTOR_HANDLE handle, void* elements, size_t numElements)
```
**SRS_VECTOR_10_014: [**VECTOR_erase shall remove the `numElements` starting at `elements` and reduce its internal storage.**]**
**SRS_VECTOR_10_015: [**VECTOR_erase shall return if `handle` is NULL.**]**
**SRS_VECTOR_10_038: [**VECTOR_erase shall return if `elements` is NULL.**]**
**SRS_VECTOR_10_040: [**VECTOR_erase shall return if `elements` is out of bound.**]**
**SRS_VECTOR_10_041: [**VECTOR_erase shall return if `elements` is misaligned.**]**
**SRS_VECTOR_10_039: [**VECTOR_erase shall return if `numElements` is 0.**]**
**SRS_VECTOR_10_027: [**VECTOR_erase shall return if `numElements` is out of bound.**]**
**SRS_VECTOR_10_014: [** VECTOR_erase shall remove the `numElements` starting at `elements` and reduce its internal storage. **]**
**SRS_VECTOR_10_015: [** VECTOR_erase shall return if `handle` is NULL. **]**
**SRS_VECTOR_10_038: [** VECTOR_erase shall return if `elements` is NULL. **]**
**SRS_VECTOR_10_040: [** VECTOR_erase shall return if `elements` is out of bound. **]**
**SRS_VECTOR_10_041: [** VECTOR_erase shall return if `elements` is misaligned. **]**
**SRS_VECTOR_10_039: [** VECTOR_erase shall return if `numElements` is 0. **]**
**SRS_VECTOR_10_027: [** VECTOR_erase shall return if `numElements` is out of bound. **]**
### VECTOR_clear
### VECTOR_clear
```c
void VECTOR_clear(VECTOR_HANDLE handle)
```
**SRS_VECTOR_10_016: [**VECTOR_clear shall remove all elements from the object and release internal storage.**]**
**SRS_VECTOR_10_017: [**VECTOR_clear shall return if the object is NULL or empty.**]**
**SRS_VECTOR_10_016: [** VECTOR_clear shall remove all elements from the object and release internal storage. **]**
### VECTOR_element
**SRS_VECTOR_10_017: [** VECTOR_clear shall return if the object is NULL or empty. **]**
### VECTOR_element
```c
void* VECTOR_element(VECTOR_HANDLE handle, size_t index)
```
**SRS_VECTOR_10_018: [**VECTOR_element shall return a pointer to the element at the given index.**]**
**SRS_VECTOR_10_019: [**VECTOR_element shall fail and return NULL if handle is NULL.**]**
**SRS_VECTOR_10_020: [**VECTOR_element shall fail and return NULL if the given index is out of range.**]**
**SRS_VECTOR_10_018: [** VECTOR_element shall return a pointer to the element at the given index. **]**
### VECTOR_front
**SRS_VECTOR_10_019: [** VECTOR_element shall fail and return NULL if handle is NULL. **]**
**SRS_VECTOR_10_020: [** VECTOR_element shall fail and return NULL if the given index is out of range. **]**
### VECTOR_front
```c
void* VECTOR_front(VECTOR_HANDLE handle)
```
**SRS_VECTOR_10_021: [**VECTOR_front shall return the element at index 0.**]**
**SRS_VECTOR_10_022: [**VECTOR_front shall fail and return NULL if handle is NULL.**]**
**SRS_VECTOR_10_028: [**VECTOR_front shall fail and return NULL if the vector is empty.**]**
**SRS_VECTOR_10_021: [** VECTOR_front shall return the element at index 0. **]**
### VECTOR_back
**SRS_VECTOR_10_022: [** VECTOR_front shall fail and return NULL if handle is NULL. **]**
**SRS_VECTOR_10_028: [** VECTOR_front shall fail and return NULL if the vector is empty. **]**
### VECTOR_back
```c
void* VECTOR_back(VECTOR_HANDLE handle)
```
**SRS_VECTOR_10_023: [**VECTOR_back shall return the last element of the vector.**]**
**SRS_VECTOR_10_024: [**VECTOR_back shall fail and return NULL if handle is NULL.**]**
**SRS_VECTOR_10_029: [**VECTOR_back shall fail and return NULL if the vector is empty.**]**
**SRS_VECTOR_10_023: [** VECTOR_back shall return the last element of the vector. **]**
### VECTOR_find_if
**SRS_VECTOR_10_024: [** VECTOR_back shall fail and return NULL if handle is NULL. **]**
**SRS_VECTOR_10_029: [** VECTOR_back shall fail and return NULL if the vector is empty. **]**
### VECTOR_find_if
```c
void* VECTOR_find_if(VECTOR_HANDLE handle, PREDICATE_FUNCTION pred, const void* value)
```
**SRS_VECTOR_10_030: [**VECTOR_find_if shall fail and return NULL if `handle` is NULL.**]**
**SRS_VECTOR_10_036: [**VECTOR_find_if shall fail and return NULL if `pred` is NULL.**]**
**SRS_VECTOR_10_031: [**VECTOR_find_if shall return the first element in the vector that matches `pred`.**]**
**SRS_VECTOR_10_032: [**VECTOR_find_if shall return NULL if no matching element is found.**]**
**SRS_VECTOR_10_030: [** VECTOR_find_if shall fail and return NULL if `handle` is NULL. **]**
### VECTOR_size
**SRS_VECTOR_10_036: [** VECTOR_find_if shall fail and return NULL if `pred` is NULL. **]**
**SRS_VECTOR_10_031: [** VECTOR_find_if shall return the first element in the vector that matches `pred`. **]**
**SRS_VECTOR_10_032: [** VECTOR_find_if shall return NULL if no matching element is found. **]**
### VECTOR_size
```c
size_t VECTOR_size(VECTOR_HANDLE handle)
```
**SRS_VECTOR_10_025: [**VECTOR_size shall return the number of elements stored with the given handle.**]**
**SRS_VECTOR_10_026: [**VECTOR_size shall return 0 if the given handle is NULL.**]**
**SRS_VECTOR_10_025: [** VECTOR_size shall return the number of elements stored with the given handle. **]**
**SRS_VECTOR_10_026: [** VECTOR_size shall return 0 if the given handle is NULL. **]**

130
devdoc/wsio_requirements.md
Просмотреть файл

@ -23,7 +23,7 @@ typedef struct WSIO_CONFIG_TAG
extern const IO_INTERFACE_DESCRIPTION* wsio_get_interface_description(void);
```
### wsio_create
### wsio_create
```c
CONCRETE_IO_HANDLE wsio_create(void* io_create_parameters);
@ -31,24 +31,39 @@ CONCRETE_IO_HANDLE wsio_create(void* io_create_parameters);
`wsio_create` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_create` member.
**SRS_WSIO_01_001: [**`wsio_create` shall create an instance of wsio and return a non-NULL handle to it.**]**
**SRS_WSIO_01_001: [** `wsio_create` shall create an instance of wsio and return a non-NULL handle to it. **]**
**SRS_WSIO_01_065: [** If the argument `io_create_parameters` is NULL then `wsio_create` shall return NULL. **]**
**SRS_WSIO_01_066: [** `io_create_parameters` shall be used as a `WSIO_CONFIG*` . **]**
**SRS_WSIO_01_067: [** If any of the members `hostname`, `resource_name` or `protocol` is NULL in `WSIO_CONFIG` then `wsio_create` shall return NULL. **]**
**SRS_WSIO_01_068: [** If allocating memory for the new wsio instance fails then `wsio_create` shall return NULL. **]**
**SRS_WSIO_01_070: [** The underlying uws instance shall be created by calling `uws_client_create_with_io`. **]**
**SRS_WSIO_01_071: [** The arguments for `uws_client_create_with_io` shall be: **]**
**SRS_WSIO_01_185: [** - `underlying_io_interface` shall be set to the `underlying_io_interface` field in the `io_create_parameters` passed to `wsio_create`. **]**
**SRS_WSIO_01_186: [** - `underlying_io_parameters` shall be set to the `underlying_io_parameters` field in the `io_create_parameters` passed to `wsio_create`. **]**
**SRS_WSIO_01_072: [** - `hostname` set to the `hostname` field in the `io_create_parameters` passed to `wsio_create`. **]**
**SRS_WSIO_01_130: [** - `port` set to the `port` field in the `io_create_parameters` passed to `wsio_create`. **]**
**SRS_WSIO_01_128: [** - `resource_name` set to the `resource_name` field in the `io_create_parameters` passed to `wsio_create`. **]**
**SRS_WSIO_01_129: [** - `protocols` shall be filled with only one structure, that shall have the `protocol` set to the value of the `protocol` field in the `io_create_parameters` passed to `wsio_create`. **]**
**SRS_WSIO_01_075: [** If `uws_client_create_with_io` fails, then `wsio_create` shall fail and return NULL. **]**
**SRS_WSIO_01_076: [** `wsio_create` shall create a pending send IO list that is to be used to queue send packets by calling `singlylinkedlist_create`. **]**
**SRS_WSIO_01_077: [** If `singlylinkedlist_create` fails then `wsio_create` shall fail and return NULL. **]**
### wsio_destroy
### wsio_destroy
```c
void wsio_destroy(CONCRETE_IO_HANDLE ws_io);
@ -57,11 +72,14 @@ void wsio_destroy(CONCRETE_IO_HANDLE ws_io);
`wsio_destroy` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_destroy` member.
**SRS_WSIO_01_078: [** `wsio_destroy` shall free all resources associated with the wsio instance. **]**
**SRS_WSIO_01_079: [** If `ws_io` is NULL, `wsio_destroy` shall do nothing. **]**
**SRS_WSIO_01_080: [** `wsio_destroy` shall destroy the uws instance created in `wsio_create` by calling `uws_client_destroy`. **]**
**SRS_WSIO_01_081: [** `wsio_destroy` shall free the list used to track the pending send IOs by calling `singlylinkedlist_destroy`. **]**
### wsio_open
### wsio_open
```c
int wsio_open(CONCRETE_IO_HANDLE ws_io, ON_IO_OPEN_COMPLETE on_io_open_complete, void* on_io_open_complete_context, ON_BYTES_RECEIVED on_bytes_received, void* on_bytes_received_context, ON_IO_ERROR on_io_error, void* on_io_error_context);
@ -70,13 +88,18 @@ int wsio_open(CONCRETE_IO_HANDLE ws_io, ON_IO_OPEN_COMPLETE on_io_open_complete,
`wsio_open` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_open` member.
**SRS_WSIO_01_082: [** `wsio_open` shall open the underlying uws instance by calling `uws_client_open_async` and providing the uws handle created in `wsio_create` as argument. **]**
**SRS_WSIO_01_083: [** On success, `wsio_open` shall return 0. **]**
**SRS_WSIO_01_132: [** If any of the arguments `ws_io`, `on_io_open_complete`, `on_bytes_received`, `on_io_error` is NULL, `wsio_open` shall fail and return a non-zero value. **]**
**SRS_WSIO_01_165: [** `wsio_open` when CLOSING shall fail and return a non-zero value. **]**
**SRS_WSIO_01_084: [** If opening the underlying uws instance fails then `wsio_open` shall fail and return a non-zero value. **]**
**SRS_WSIO_01_131: [** `wsio_open` when already OPEN or OPENING shall fail and return a non-zero value. **]**
### wsio_close
### wsio_close
```c
int wsio_close(CONCRETE_IO_HANDLE ws_io, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
@ -85,18 +108,28 @@ int wsio_close(CONCRETE_IO_HANDLE ws_io, ON_IO_CLOSE_COMPLETE on_io_close_comple
`wsio_close` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_close` member.
**SRS_WSIO_01_085: [** `wsio_close` shall close the websockets IO if an open action is either pending or has completed successfully (if the IO is open). **]**
**SRS_WSIO_01_133: [** On success `wsio_close` shall return 0. **]**
**SRS_WSIO_01_086: [** if `ws_io` is NULL, `wsio_close` shall return a non-zero value. **]**
**SRS_WSIO_01_087: [** `wsio_close` shall call `uws_client_close_async` while passing as argument the IO handle created in `wsio_create`. **]**
**SRS_WSIO_01_164: [** When `uws_client_close` fails, `wsio_close` shall fail and return a non-zero value. **]**
**SRS_WSIO_01_088: [** `wsio_close` when no open action has been issued shall fail and return a non-zero value. **]**
**SRS_WSIO_01_089: [** `wsio_close` after a `wsio_close` shall fail and return a non-zero value. **]**
**SRS_WSIO_01_090: [** The argument `on_io_close_complete` shall be optional, if NULL is passed by the caller then no close complete callback shall be triggered. **]**
**SRS_WSIO_01_091: [** `wsio_close` shall obtain all the pending IO items by repetitively querying for the head of the pending IO list and freeing that head item. **]**
**SRS_WSIO_01_092: [** Obtaining the head of the pending IO list shall be done by calling `singlylinkedlist_get_head_item`. **]**
**SRS_WSIO_01_093: [** For each pending item the send complete callback shall be called with `IO_SEND_CANCELLED`.**\]**
### wsio_send
### wsio_send
```c
int wsio_send(CONCRETE_IO_HANDLE ws_io, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
@ -105,19 +138,30 @@ int wsio_send(CONCRETE_IO_HANDLE ws_io, const void* buffer, size_t size, ON_SEND
`wsio_send` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_send` member.
**SRS_WSIO_01_095: [** `wsio_send` shall call `uws_client_send_frame_async`, passing the `buffer` and `size` arguments as they are: **]**
**SRS_WSIO_01_098: [** On success, `wsio_send` shall return 0. **]**
**SRS_WSIO_01_100: [** If any of the arguments `ws_io` or `buffer` are NULL, `wsio_send` shall fail and return a non-zero value. **]**
**SRS_WSIO_01_099: [** If the wsio is not OPEN (open has not been called or is still in progress) then `wsio_send` shall fail and return a non-zero value. **]**
**SRS_WSIO_01_102: [** An entry shall be queued in the singly linked list by calling `singlylinkedlist_add`. **]**
**SRS_WSIO_01_103: [** The entry shall contain the `on_send_complete` callback and its context. **]**
**SRS_WSIO_01_096: [** The frame type used shall be `WS_FRAME_TYPE_BINARY`. **]**
**SRS_WSIO_01_097: [** The `is_final` argument shall be set to true. **]**
**SRS_WSIO_01_101: [** If `size` is zero then `wsio_send` shall fail and return a non-zero value. **]**
**SRS_WSIO_01_134: [** If allocating memory for the pending IO data fails, `wsio_send` shall fail and return a non-zero value. **]**
**SRS_WSIO_01_104: [** If `singlylinkedlist_add` fails, `wsio_send` shall fail and return a non-zero value. **]**
**SRS_WSIO_01_105: [** The argument `on_send_complete` shall be optional, if NULL is passed by the caller then no send complete callback shall be triggered. **]**
### wsio_dowork
### wsio_dowork
```c
void wsio_dowork(CONCRETE_IO_HANDLE ws_io);
@ -126,10 +170,12 @@ void wsio_dowork(CONCRETE_IO_HANDLE ws_io);
`wsio_dowork` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_dowork` member.
**SRS_WSIO_01_106: [** `wsio_dowork` shall call `uws_client_dowork` with the uws handle created in `wsio_create`. **]**
**SRS_WSIO_01_107: [** If the `ws_io` argument is NULL, `wsio_dowork` shall do nothing. **]**
**SRS_WSIO_01_108: [** If the IO is not yet open, `wsio_dowork` shall do nothing. **]**
### wsio_setoption
### wsio_setoption
```c
int wsio_setoption(CONCRETE_IO_HANDLE ws_io, const char* option_name, const void* value);
@ -138,13 +184,18 @@ int wsio_setoption(CONCRETE_IO_HANDLE ws_io, const char* option_name, const void
`wsio_setoption` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_setoption` member.
**SRS_WSIO_01_109: [** If any of the arguments `ws_io` or `option_name` is NULL `wsio_setoption` shall return a non-zero value. **]**
**SRS_WSIO_01_183: [** If the option name is `WSIOOptions` then `wsio_setoption` shall call `OptionHandler_FeedOptions` and pass to it the underlying IO handle and the `value` argument. **]**
**SRS_WSIO_01_184: [** If `OptionHandler_FeedOptions` fails, `wsio_setoption` shall fail and return a non-zero value. **]**
**SRS_WSIO_01_156: [** Otherwise all options shall be passed as they are to uws by calling `uws_client_set_option`. **]**
**SRS_WSIO_01_158: [** On success, `wsio_setoption` shall return 0. **]**
**SRS_WSIO_01_157: [** If `uws_client_set_option` fails, `wsio_setoption` shall fail and return a non-zero value. **]**
### wsio_retrieveoptions
### wsio_retrieveoptions
```c
OPTIONHANDLER_HANDLE wsio_retrieveoptions(CONCRETE_IO_HANDLE handle)
@ -153,15 +204,22 @@ OPTIONHANDLER_HANDLE wsio_retrieveoptions(CONCRETE_IO_HANDLE handle)
`wsio_retrieveoptions` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_retrieveoptions` member.
**SRS_WSIO_01_118: [** If parameter `handle` is `NULL` then `wsio_retrieveoptions` shall fail and return NULL. **]**
**SRS_WSIO_01_119: [** `wsio_retrieveoptions` shall call `OptionHandler_Create` to produce an `OPTIONHANDLER_HANDLE` and on success return the new `OPTIONHANDLER_HANDLE` handle. **]**
**SRS_WSIO_01_120: [** If `OptionHandler_Create` fails then `wsio_retrieveoptions` shall fail and return NULL. **]**
**SRS_WSIO_01_178: [** `uws_client_retrieve_options` shall add to the option handler one option, whose name shall be `uWSCLientOptions` and the value shall be queried by calling `uws_client_retrieve_options`. **]**
**SRS_WSIO_01_179: [** When calling `uws_client_retrieve_options` the uws client handle shall be passed to it. **]**
**SRS_WSIO_01_180: [** If `uws_client_retrieve_options` fails, `uws_client_retrieve_options` shall fail and return NULL. **]**
**SRS_WSIO_01_181: [** Adding the option shall be done by calling `OptionHandler_AddOption`. **]**
**SRS_WSIO_01_182: [** If `OptionHandler_AddOption` fails, `uws_client_retrieve_options` shall fail and return NULL. **]**
### wsio_clone_option
### wsio_clone_option
`wsio_clone_option` is the implementation provided to the option handler instance created as part of `wsio_retrieve_options`.
@ -170,10 +228,12 @@ void* wsio_clone_option(const char* name, const void* value)
```
**SRS_WSIO_01_171: [** `wsio_clone_option` called with `name` being `WSIOOptions` shall return the same value. **]**
**SRS_WSIO_01_173: [** `wsio_clone_option` called with any other option name than `WSIOOptions` shall return NULL. **]**
**SRS_WSIO_01_174: [** If `wsio_clone_option` is called with NULL `name` or `value` it shall return NULL. **]**
### wsio_destroy_option
### wsio_destroy_option
`wsio_destroy_option` is the implementation provided to the option handler instance created as part of `wsio_retrieve_options`.
@ -182,67 +242,99 @@ void wsio_destroy_option(const char* name, const void* value)
```
**SRS_WSIO_01_175: [** `wsio_destroy_option` called with the option `name` being `WSIOOptions` shall destroy the value by calling `OptionHandler_Destroy`. **]**
**SRS_WSIO_01_176: [** If `wsio_destroy_option` is called with any other `name` it shall do nothing. **]**
**SRS_WSIO_01_177: [** If `wsio_destroy_option` is called with NULL `name` or `value` it shall do nothing. **]**
### wsio_get_interface_description
### wsio_get_interface_description
```c
const IO_INTERFACE_DESCRIPTION* wsio_get_interface_description(void);
```
**SRS_WSIO_01_064: [**wsio_get_interface_description shall return a pointer to an IO_INTERFACE_DESCRIPTION structure that contains pointers to the functions: wsio_retrieveoptions, wsio_create, wsio_destroy, wsio_open, wsio_close, wsio_send and wsio_dowork.**]**
**SRS_WSIO_01_064: [** wsio_get_interface_description shall return a pointer to an IO_INTERFACE_DESCRIPTION structure that contains pointers to the functions: wsio_retrieveoptions, wsio_create, wsio_destroy, wsio_open, wsio_close, wsio_send and wsio_dowork. **]**
### on_underlying_ws_error
### on_underlying_ws_error
**SRS_WSIO_01_121: [** When `on_underlying_ws_error` is called while the IO is OPEN the wsio instance shall be set to ERROR and an error shall be indicated via the `on_io_error` callback passed to `wsio_open`. **]**
**SRS_WSIO_01_123: [** When calling `on_io_error`, the `on_io_error_context` argument given in `wsio_open` shall be passed to the callback `on_io_error`. **]**
**SRS_WSIO_01_122: [** When `on_underlying_ws_error` is called while the IO is OPENING, the `on_io_open_complete` callback passed to `wsio_open` shall be called with `IO_OPEN_ERROR`. **]**
**SRS_WSIO_01_135: [** When `on_underlying_ws_error` is called with a NULL context, it shall do nothing. **]**
### on_underlying_ws_frame_received
### on_underlying_ws_frame_received
**SRS_WSIO_01_124: [** When `on_underlying_ws_frame_received` is called the bytes in the frame shall be indicated by calling the `on_bytes_received` callback passed to `wsio_open`. **]**
**SRS_WSIO_01_125: [** When calling `on_bytes_received`, the `on_bytes_received_context` argument given in `wsio_open` shall be passed to the callback `on_bytes_received`. **]**
**SRS_WSIO_01_126: [** If `on_underlying_ws_frame_received` is called while the IO is in any state other than OPEN, it shall do nothing. **]**
**SRS_WSIO_01_150: [** If `on_underlying_ws_frame_received` is called with NULL context it shall do nothing. **]**
**SRS_WSIO_01_151: [** If the WebSocket frame type is not binary then an error shall be indicated by calling the `on_io_error` callback passed to `wsio_open`. **]**
**SRS_WSIO_01_153: [** When `on_underlying_ws_frame_received` is called with zero `size`, no bytes shall be indicated up as received. **]**
**SRS_WSIO_01_154: [** When `on_underlying_ws_frame_received` is called with a positive `size` and a NULL `buffer`, an error shall be indicated by calling the `on_io_error` callback passed to `wsio_open`. **]**
**SRS_WSIO_01_152: [** When calling `on_io_error`, the `on_io_error_context` argument given in `wsio_open` shall be passed to the callback `on_io_error`. **]**
### on_underlying_ws_open_complete
### on_underlying_ws_open_complete
**SRS_WSIO_01_136: [** When `on_underlying_ws_open_complete` is called with `WS_OPEN_OK` while the IO is opening, the callback `on_io_open_complete` shall be called with `IO_OPEN_OK`. **]**
**SRS_WSIO_01_149: [** When `on_underlying_ws_open_complete` is called with `WS_OPEN_CANCELLED` while the IO is opening, the callback `on_io_open_complete` shall be called with `IO_OPEN_CANCELLED`. **]**
**SRS_WSIO_01_137: [** When `on_underlying_ws_open_complete` is called with any other error code while the IO is opening, the callback `on_io_open_complete` shall be called with `IO_OPEN_ERROR`. **]**
**SRS_WSIO_01_138: [** When `on_underlying_ws_open_complete` is called with a NULL context, it shall do nothing. **]**
**SRS_WSIO_01_139: [** When `on_underlying_ws_open_complete` is called while in OPEN state it shall indicate an error by calling the `on_io_error` callback passed to `wsio_open` and switch to the ERROR state. **]**
**SRS_WSIO_01_141: [** When `on_underlying_ws_open_complete` is called while in the ERROR state it shall indicate an error by calling the `on_io_error` callback passed to `wsio_open`. **]**
**SRS_WSIO_01_140: [** When calling `on_io_error`, the `on_io_error_context` argument given in `wsio_open` shall be passed to the callback `on_io_error`. **]**
**SRS_WSIO_01_142: [** When `on_underlying_ws_open_complete` is called while in the CLOSING state an error shall be indicated by calling the `on_io_error` callback passed to `wsio_open`. **]**
### on_underlying_ws_send_frame_complete
### on_underlying_ws_send_frame_complete
**SRS_WSIO_01_143: [** When `on_underlying_ws_send_frame_complete` is called after sending a WebSocket frame, the pending IO shall be removed from the list. **]**
**SRS_WSIO_01_145: [** Removing it from the list shall be done by calling `singlylinkedlist_remove`. **]**
**SRS_WSIO_01_144: [** Also the pending IO data shall be freed. **]**
**SRS_WSIO_01_146: [** When `on_underlying_ws_send_frame_complete` is called with `WS_SEND_OK`, the callback `on_send_complete` shall be called with `IO_SEND_OK`. **]**
**SRS_WSIO_01_147: [** When `on_underlying_ws_send_frame_complete` is called with `WS_SEND_CANCELLED`, the callback `on_send_complete` shall be called with `IO_SEND_CANCELLED`. **]**
**SRS_WSIO_01_148: [** When `on_underlying_ws_send_frame_complete` is called with any other error code, the callback `on_send_complete` shall be called with `IO_SEND_ERROR`. **]**
**SRS_WSIO_01_155: [** When `on_underlying_ws_send_frame_complete` is called with a NULL context it shall do nothing. **]**
### on_underlying_ws_close_complete
### on_underlying_ws_close_complete
**SRS_WSIO_01_159: [** When `on_underlying_ws_close_complete` while the IO is closing (after `wsio_close`), the close shall be indicated up by calling the `on_io_close_complete` callback passed to `wsio_close`. **]**
**SRS_WSIO_01_163: [** When `on_io_close_complete` is called, the context passed to `wsio_close` shall be passed as argument to `on_io_close_complete`. **]**
**SRS_WSIO_01_160: [** If NULL was passed to `wsio_close` no callback shall be called. **]**
**SRS_WSIO_01_161: [** If the context passed to `on_underlying_ws_close_complete` is NULL, `on_underlying_ws_close_complete` shall do nothing. **]**
### on_underlying_ws_peer_closed
### on_underlying_ws_peer_closed
**SRS_WSIO_01_166: [** When `on_underlying_ws_peer_closed` and the state of the IO is OPEN an error shall be indicated by calling the `on_io_error` callback passed to `wsio_open`. **]**
**SRS_WSIO_01_169: [** When `on_underlying_ws_peer_closed` and the state of the IO is CLOSING an error shall be indicated by calling the `on_io_error` callback passed to `wsio_open`. **]**
**SRS_WSIO_01_170: [** When `on_underlying_ws_peer_closed` and the state of the IO is OPENING an error shall be indicated by calling the `on_io_open_complete` callback passed to `wsio_open` with the error code `IO_OPEN_ERROR`. **]**
**SRS_WSIO_01_168: [** The `close_code`, `extra_data` and `extra_data_length` arguments shall be ignored. **]**
**SRS_WSIO_01_167: [** If `on_underlying_ws_peer_closed` is called with a NULL context it shall do nothing. **]**

4
devdoc/x509_openssl.md
Просмотреть файл

@ -16,7 +16,7 @@ int x509_openssl_add_credentials(SSL_CTX* ssl_ctx, const char* x509certificate,
int x509_openssl_add_certificates(SSL_CTX, ssl_ctx, const char* certificates);
```
### x509_openssl_add_credentials
### x509_openssl_add_credentials
```c
int x509_openssl_add_credentials(SSL_CTX* ssl_ctx, const char* x509certificate, const char* x509privatekey);
```
@ -42,7 +42,7 @@ x509_openssl_add_credentials loads a x509 certificate and a x509 private key int
**SRS_X509_OPENSSL_02_009: [** Otherwise x509_openssl_add_credentials shall fail and return a non-zero number. **]**
### x509_openssl_add_certificates
### x509_openssl_add_certificates
```c
int x509_openssl_add_certificates(SSL_CTX* ssl_ctx, const char* certificates);
```

18
devdoc/x509_schannel.md
Просмотреть файл

@ -19,7 +19,7 @@ void x509_schannel_destroy(X509_SCHANNEL_HANDLE, x509_schannel_handle);
PCCERT_CONTEXT x509_schannel_get_certificate_context(X509_SCHANNEL_HANDLE x509_schannel_handle);
```
### x509_schannel_create
### x509_schannel_create
```c
X509_SCHANNEL_HANDLE x509_schannel_create(const char* x509certificate, const char* x509privatekey);
```
@ -27,28 +27,37 @@ X509_SCHANNEL_HANDLE x509_schannel_create(const char* x509certificate, const cha
x509_schannel_create creates a handle wrapping a PCCERT_CONTEXT and other information.
**SRS_X509_SCHANNEL_02_001: [** If `x509certificate` or `x509privatekey` are NULL then x509_schannel_create shall fail and return NULL. **]**
**SRS_X509_SCHANNEL_02_002: [** `x509_schannel_create` shall convert the certificate to binary form by calling `CryptStringToBinaryA`. **]**
**SRS_X509_SCHANNEL_02_003: [** `x509_schannel_create` shall convert the private key to binary form by calling `CryptStringToBinaryA`. **]**
**SRS_X509_SCHANNEL_02_004: [** `x509_schannel_create` shall decode the private key by calling `CryptDecodeObjectEx`. **]**
**SRS_X509_SCHANNEL_02_005: [** `x509_schannel_create` shall call `CryptAcquireContext`. **]**
**SRS_X509_SCHANNEL_02_006: [** `x509_schannel_create` shall import the private key by calling `CryptImportKey`. **]**
**SRS_X509_SCHANNEL_02_007: [** `x509_schannel_create` shall create a cerficate context by calling `CertCreateCertificateContext`. **]**
**SRS_X509_SCHANNEL_02_008: [** `x509_schannel_create` shall call set the certificate private key by calling `CertSetCertificateContextProperty`. **]**
**SRS_X509_SCHANNEL_02_009: [** If all the operations above succeed, then `x509_schannel_create` shall succeeds and return a non-NULL X509_SCHANNEL_HANDLE. **]**
**SRS_X509_SCHANNEL_02_009: [** If all the operations above succeed, then `x509_schannel_create` shall succeeds and return a non-NULL X509_SCHANNEL_HANDLE. **]**
**SRS_X509_SCHANNEL_02_010: [** Otherwise, `x509_schannel_create` shall fail and return a NULL X509_SCHANNEL_HANDLE. **]**
### x509_schannel_destroy
### x509_schannel_destroy
```c
void x509_schannel_destroy(X509_SCHANNEL_HANDLE x509_schannel_handle)
```
`x509_schannel_destroy` frees the system resources used by a `X509_SCHANNEL_HANDLE`
**SRS_X509_SCHANNEL_02_011: [** If parameter `x509_schannel_handle` is NULL then `x509_schannel_destroy` shall do nothing. **]**
**SRS_X509_SCHANNEL_02_012: [** Otherwise, `x509_schannel_destroy` shall free all used resources. **]**
### x509_schannel_get_certificate_context
### x509_schannel_get_certificate_context
```c
PCCERT_CONTEXT x509_schannel_get_certificate_context(X509_SCHANNEL_HANDLE x509_schannel_handle)
```
@ -56,4 +65,5 @@ PCCERT_CONTEXT x509_schannel_get_certificate_context(X509_SCHANNEL_HANDLE x509_s
x509_schannel_get_certificate_context returns the constructed certificate context (PCCERT_CONTEXT)
**SRS_X509_SCHANNEL_02_013: [** If parameter `x509_schannel_handle` is NULL then x509_schannel_get_certificate_context shall return NULL. **]**
**SRS_X509_SCHANNEL_02_014: [** Otherwise, `x509_schannel_get_certificate_context` shall return a non-NULL PCCERT_CONTEXT pointer. **]**

115
devdoc/xio_requirements.md
Просмотреть файл

@ -1,11 +1,11 @@
xio requirements
================
##Overview
## Overview
xio is module that implements an IO interface, abstracting from upper layers the functionality of simply sending or receiving a sequence of bytes.
##Exposed API
## Exposed API
```c
typedef struct XIO_INSTANCE_TAG* XIO_HANDLE;
@ -61,94 +61,123 @@ extern void xio_dowork(XIO_HANDLE xio);
extern int xio_setoption(XIO_HANDLE xio, const char* optionName, const void* value);
```
###xio_create
### xio_create
```c
extern XIO_HANDLE xio_create(const IO_INTERFACE_DESCRIPTION* io_interface_description, const void* io_create_parameters);
```
**SRS_XIO_01_001: [**xio_create shall return on success a non-NULL handle to a new IO interface.**]**
**SRS_XIO_01_002: [**In order to instantiate the concrete IO implementation the function concrete_xio_create from the io_interface_description shall be called, passing the xio_create_parameters argument.**]**
**SRS_XIO_01_016: [**If the underlying concrete_xio_create call fails, xio_create shall return NULL.**]**
**SRS_XIO_01_003: [**If the argument io_interface_description is NULL, xio_create shall return NULL.**]**
**SRS_XIO_01_004: [**If any io_interface_description member is NULL, xio_create shall return NULL.**]**
**SRS_XIO_01_017: [**If allocating the memory needed for the IO interface fails then xio_create shall return NULL.**]**
**SRS_XIO_01_001: [** xio_create shall return on success a non-NULL handle to a new IO interface. **]**
###xio_destroy
**SRS_XIO_01_002: [** In order to instantiate the concrete IO implementation the function concrete_xio_create from the io_interface_description shall be called, passing the xio_create_parameters argument. **]**
**SRS_XIO_01_016: [** If the underlying concrete_xio_create call fails, xio_create shall return NULL. **]**
**SRS_XIO_01_003: [** If the argument io_interface_description is NULL, xio_create shall return NULL. **]**
**SRS_XIO_01_004: [** If any io_interface_description member is NULL, xio_create shall return NULL. **]**
**SRS_XIO_01_017: [** If allocating the memory needed for the IO interface fails then xio_create shall return NULL. **]**
### xio_destroy
```c
extern void xio_destroy(XIO_HANDLE xio);
```
**SRS_XIO_01_005: [**xio_destroy shall free all resources associated with the IO handle.**]**
**SRS_XIO_01_006: [**xio_destroy shall also call the concrete_xio_destroy function that is member of the io_interface_description argument passed to xio_create, while passing as argument to concrete_xio_destroy the result of the underlying concrete_xio_create handle that was called as part of the xio_create call.**]**
**SRS_XIO_01_007: [**If the argument io is NULL, xio_destroy shall do nothing.**]**
**SRS_XIO_01_005: [** xio_destroy shall free all resources associated with the IO handle. **]**
###xio_open
**SRS_XIO_01_006: [** xio_destroy shall also call the concrete_xio_destroy function that is member of the io_interface_description argument passed to xio_create, while passing as argument to concrete_xio_destroy the result of the underlying concrete_xio_create handle that was called as part of the xio_create call. **]**
**SRS_XIO_01_007: [** If the argument io is NULL, xio_destroy shall do nothing. **]**
### xio_open
```c
extern int xio_open(XIO_HANDLE xio, ON_IO_OPEN_COMPLETE on_io_open_complete, void* on_io_open_complete_context, ON_BYTES_RECEIVED on_bytes_received, void* on_bytes_received_context, ON_IO_ERROR on_io_error, void* on_io_error_context);
```
**SRS_XIO_01_019: [**xio_open shall call the specific concrete_xio_open function specified in xio_create, passing callback function and context arguments for three events: open completed, bytes received, and IO error.**]**
**SRS_XIO_01_020: [**On success, xio_open shall return 0.**]**
**SRS_XIO_01_021: [**If handle is NULL, xio_open shall return a non-zero value.**]**
**SRS_XIO_01_022: [**If the underlying concrete_xio_open fails, xio_open shall return a non-zero value.**]**
**SRS_XIO_01_019: [** xio_open shall call the specific concrete_xio_open function specified in xio_create, passing callback function and context arguments for three events: open completed, bytes received, and IO error. **]**
###xio_close
**SRS_XIO_01_020: [** On success, xio_open shall return 0. **]**
**SRS_XIO_01_021: [** If handle is NULL, xio_open shall return a non-zero value. **]**
**SRS_XIO_01_022: [** If the underlying concrete_xio_open fails, xio_open shall return a non-zero value. **]**
### xio_close
```c
extern int xio_close(XIO_HANDLE xio, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
```
**SRS_XIO_01_023: [**xio_close shall call the specific concrete_xio_close function specified in xio_create.**]**
**SRS_XIO_01_024: [**On success, xio_close shall return 0.**]**
**SRS_XIO_01_025: [**If the argument io is NULL, xio_close shall return a non-zero value.**]**
**SRS_XIO_01_026: [**If the underlying concrete_xio_close fails, xio_close shall return a non-zero value.**]**
**SRS_XIO_01_023: [** xio_close shall call the specific concrete_xio_close function specified in xio_create. **]**
###xio_send
**SRS_XIO_01_024: [** On success, xio_close shall return 0. **]**
**SRS_XIO_01_025: [** If the argument io is NULL, xio_close shall return a non-zero value. **]**
**SRS_XIO_01_026: [** If the underlying concrete_xio_close fails, xio_close shall return a non-zero value. **]**
### xio_send
```c
extern int xio_send(XIO_HANDLE xio, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
```
**SRS_XIO_01_008: [**xio_send shall pass the sequence of bytes pointed to by buffer to the concrete IO implementation specified in xio_create, by calling the concrete_xio_send function while passing down the buffer and size arguments to it.**]**
**SRS_XIO_01_027: [**xio_send shall pass to the concrete_xio_send function the on_send_complete and callback_context arguments.**]**
**SRS_XIO_01_009: [**On success, xio_send shall return 0.**]**
**SRS_XIO_01_010: [**If the argument xio is NULL, xio_send shall return a non-zero value.**]**
**SRS_XIO_01_015: [**If the underlying concrete_xio_send fails, xio_send shall return a non-zero value.**]**
**SRS_XIO_01_011: [**No error check shall be performed on buffer and size.**]**
**SRS_XIO_01_008: [** xio_send shall pass the sequence of bytes pointed to by buffer to the concrete IO implementation specified in xio_create, by calling the concrete_xio_send function while passing down the buffer and size arguments to it. **]**
###xio_dowork
**SRS_XIO_01_027: [** xio_send shall pass to the concrete_xio_send function the on_send_complete and callback_context arguments. **]**
**SRS_XIO_01_009: [** On success, xio_send shall return 0. **]**
**SRS_XIO_01_010: [** If the argument xio is NULL, xio_send shall return a non-zero value. **]**
**SRS_XIO_01_015: [** If the underlying concrete_xio_send fails, xio_send shall return a non-zero value. **]**
**SRS_XIO_01_011: [** No error check shall be performed on buffer and size. **]**
### xio_dowork
```c
extern void xio_dowork(XIO_HANDLE xio);
```
**SRS_XIO_01_012: [**xio_dowork shall call the concrete IO implementation specified in xio_create, by calling the concrete_xio_dowork function.**]**
**SRS_XIO_01_013: [**On success, xio_send shall return 0.**]**
**SRS_XIO_01_014: [**If the underlying concrete_xio_dowork fails, xio_dowork shall return a non-zero value.**]**
**SRS_XIO_01_018: [**When the io argument is NULL, xio_dowork shall do nothing.**]**
**SRS_XIO_01_012: [** xio_dowork shall call the concrete IO implementation specified in xio_create, by calling the concrete_xio_dowork function. **]**
###xio_setoption
**SRS_XIO_01_013: [** On success, xio_send shall return 0. **]**
**SRS_XIO_01_014: [** If the underlying concrete_xio_dowork fails, xio_dowork shall return a non-zero value. **]**
**SRS_XIO_01_018: [** When the io argument is NULL, xio_dowork shall do nothing. **]**
### xio_setoption
```c
extern int xio_setoption(XIO_HANDLE xio, const char* optionName, const void* value);
```
**SRS_XIO_03_028: [**xio_setoption shall pass the optionName and value to the concrete IO implementation specified in xio_create by invoking the concrete_xio_setoption function.**]**
**SRS_XIO_03_029: [**xio_setoption shall return 0 upon success.**]**
**SRS_XIO_03_030: [**If the xio argument or the optionName argument is NULL, xio_setoption shall return a non-zero value.**]**
**SRS_XIO_03_031: [**If the underlying concrete_xio_setoption fails, xio_setOption shall return a non-zero value.**]**
**SRS_XIO_03_028: [** xio_setoption shall pass the optionName and value to the concrete IO implementation specified in xio_create by invoking the concrete_xio_setoption function. **]**
### xio_retrieveoptions
**SRS_XIO_03_029: [** xio_setoption shall return 0 upon success. **]**
**SRS_XIO_03_030: [** If the xio argument or the optionName argument is NULL, xio_setoption shall return a non-zero value. **]**
**SRS_XIO_03_031: [** If the underlying concrete_xio_setoption fails, xio_setOption shall return a non-zero value. **]**
### xio_retrieveoptions
```
OPTIONHANDLER_HANDLE xio_retrieveoptions(XIO_HANDLE xio)
```
**SRS_XIO_02_001: [** If argument `xio` is `NULL` then `xio_retrieveoptions` shall fail and return `NULL`. **]**
**SRS_XIO_02_002: [** `xio_retrieveoptions` shall create a `OPTIONHANDLER_HANDLE` by calling `OptionHandler_Create` passing `xio_setoption` as `setOption` argument and `xio_CloneOption` and `xio_DestroyOption` for `cloneOption` and `destroyOption`. **]**
**SRS_XIO_02_003: [** `xio_retrieveoptions` shall retrieve the concrete handle's options by a call to `concrete_io_retrieveoptions`. **]**
**SRS_XIO_02_004: [** `xio_retrieveoptions` shall add a hardcoded option named `concreteOptions` having the same content as the concrete handle's options. **]**
**SRS_XIO_02_005: [** If any operation fails, then `xio_retrieveoptions` shall fail and return NULL. **]**
**SRS_XIO_02_006: [** Otherwise, `xio_retrieveoptions` shall succeed and return a non-NULL handle. **]**
**SRS_XIO_02_006: [** Otherwise, `xio_retrieveoptions` shall succeed and return a non-NULL handle. **]**