Update README

Author: kosmas-valianos

README.md

@@ -10,48 +10,54 @@ The library should be compilable to any platform as it is written in ANSI C. It
 
 ## API
 ### Parsing
-**`pp_parse()`**: parsing a PROXY protocol header. Parameters:
-* `uint8_t *pkt`: Pointer to a buffer with the data to parse. Normally it will be the buffer used to peek data from a socket.
-* `uint32_t pktlen`: Data's length. Normally it will be the return value of a `recv(MSG_PEEK)`.
-* `pp_info_t *proxy_info`: Pointer to a `pp_info_t` variable which will be used to save all the extracted information of the PROXY protocol header including the TLVs
-* `return value: int32_t`: The length of the PROXY protocol header in case of success or a negative integer in case of error. You can use `pp_strerror()` to get a descriptive error message. In case the data dont't match any of the v1/v2 signatures `0` is returned.
+**`int32_t pp_parse_hdr(uint8_t *buffer, uint32_t buffer_length, pp_info_t *pp_info)`**:
 
-You shall not pass your `pp_info_t` variable to `pp_parse()` again without first clearing it with `pp_info_clear()` (see below)
+Inpects the buffer for a PROXY protocol header and extracts all the information if any.
+* `buffer`:         Pointer to a buffer with the data to parse. Normally it will be the buffer used to peek data from a socket.
+* `buffer_length`:  Buffer's length. Typically the bytes read from the `recv(MSG_PEEK)` operation.
+* `pp_info`:        Pointer to a `pp_info_t` structure which will get filled with all the extracted information.
+* `return`:
+   * \> 0 Length of the PROXY protocol header
+   * == 0 No PROXY protocol header found
+   * <  0 Error occurred. `pp_strerror()` with that value can be used to get a descriptive message
 
-**`pp_info_get_tlv_value()`**: extracting TLVs' values. Parameters:
-* `pp_info_t *pp_info`: The `pp_info_t` used in the `pp_parse()`
-* `uint8_t type`: The type of the TLV you are looking for as per the specification e.g. PP2_TYPE_AWS, PP2_TYPE_AZURE etc.
-* `uint8_t subtype`: The subtype of the TLV you are looking for (in case it is needed else 0 to get it ignored) as per the specification e.g. PP2_SUBTYPE_AWS_VPCE_ID, PP2_SUBTYPE_AZURE_PRIVATEENDPOINT_LINKID
-* `uint16_t *value_len_out`: The length of the value so that applications can copy and use the value properly
-* `return value: uint8_t *`: Pointer to the value. In case the value is a string e.g. PP2_TYPE_AWS-PP2_SUBTYPE_AWS_VPCE_ID then the buffer is NULL terminated so that it can be used directly for string operations like `strcmp()` etc. **Do not manipulate these data in any way, rather make copies of them if you need to modify them.**
+You shall not pass your `pp_info_t` variable to `pp_parse()` again without first clearing it with `pp_info_clear()`
 
-**`pp_info_clear()`**: clearing a `pp_info_t` structure. You **MUST** use it. Parameter:
-* `pp_info_t *pp_info`: A pointer to the `pp_info_t` used in `pp_parse()`
+**`void pp_info_clear(pp_info_t *pp_info)`**
 
-It basically clears the saved TLVs structure. For v1 it is not really needed as there are not any TLVs but to be safe always use it! A PROXY protocol sender might change from v1 to v2 so better to have your application prepared.
+Clears the `pp_info_t` structure and frees any allocated memory associated with it. Shall always be called after a call to `pp_parse()`
+* `pp_info`: Pointer to a filled `pp_info_t` structure which has been used to a previous call to `pp_parse()`
+
+**`const uint8_t *pp_info_get_*(const pp_info_t *pp_info, uint16_t *length);`**
+
+Searches for the specified TLV and returns its value
+* `pp_info` Pointer to a `pp_info_t` structure used in `pp_parse()`
+* `length`  Pointer to a `uint16_t` where the TLV's value length will be set
+* `return`  Pointer to a buffer holding the TLV's value if found else `NULL`. In case of US-ASCII value the buffer is `NULL` terminated
 
 ### Creating
-**`pp_create_hdr()`**: create a PROXY protocol header. Parameters:
-* `uint8_t version`: `1` or `2` depending on the PROXY protocol version you want to use.
-* `uint8_t fam`: Transport and address family. The values match exactly the specification:
-  * v2 
-    * `'\x00'` : UNSPEC
-    * `'\x11'` : TCP over IPv4
-    * `'\x12'` : UDP over IPv4
-    * `'\x21'` : TCP over IPv6
-    * `'\x22'` : UDP over IPv6
-    * `'\x31'` : UNIX stream
-    * `'\x32'` : UNIX datagram
-  * v1
-    * `AF_INET`
-    * `AF_INET6`
-* `pp_info_t *pp_info` : Pointer to a filled `pp_info_t` structure. Note that at the moment tlvs from the `tlv_array_t tlv_array` inside it will not be included in the header. This functionality will be added with the next release.
-* `uint32_t *pp_hdr_len`: Output parameter where the length of the the PROXY protocol header will be stored.
-* `uint32_t *error`: Outpur parameter where its value will be set to a negative integer in case of error or `ERR_NULL` in case of success. You can use `pp_strerror()` to get a descriptive error message
-* `return value: uint8_t *`: Pointer to a dynamically allocated buffer where the PROXY protocol header exists. Shall be freed with `free()`
+**`uint8_t *pp_create_hdr(uint8_t version, const pp_info_t *pp_info, uint16_t *pp_hdr_len, int32_t *error)`**:
+
+Creates a PROXY protocol header considering the information inside the pp_info.
+* `version`:
+   * 0 Create a v1 PROXY protocol header.
+   * 1 Create a v2 PROXY protocol header.
+* `pp_info`:    Pointer to a filled `pp_info_t` structure whose information will be used for the creation of the PROXY protocol header.
+* `pp_hdr_len`: Pointer to a `uint16_t` where the length of the create PROXY protocol header will be set
+* `error`:      Pointer to a `int32_t` where the error value will be set
+   * `ERR_NULL` No error occurred
+   * < 0        Error
+* `return`: Pointer to a heap allocated buffer containing the PROXY protocol header. Must be freed with free()
+
+### Error reporting
+**`const char *pp_strerror(int32_t error)`**
+
+Returns a descriptive error message
+* `error`:  `int32_t` value from other API functions
+* `return`: Pointer to the descriptive message if the error value is recognized else `NULL`
 
 ## Example
 See `examples/client_server.c`
 
 ## In progress
-* Creating v2 PROXY protocol headers with TLVs is not yet supported. Will be added in the next release
+* Creating v2 PROXY protocol headers with TLVs is not yet supported. Will be added in the next major release

src/proxy_protocol.h

@@ -100,7 +100,7 @@ typedef struct
 /* Returns a descriptive error message
  *
  * error    int32_t value from other API functions
- * return   Pointer to the descriptive message if error value is recognized else NULL
+ * return   Pointer to the descriptive message if the error value is recognized else NULL
  */
 const char *pp_strerror(int32_t error);