diff options
author | Matt Caswell <matt@openssl.org> | 2016-09-08 11:44:25 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2016-09-13 09:41:21 +0100 |
commit | 9bf85bf9c52359813b5f9f6709b381497671d625 (patch) | |
tree | 2ab422c6b18f7be6d0d469fb9d09a4bef48c7678 /ssl/packet_locl.h | |
parent | d6c4cc293974e622b387458d2293e29f8f14fbbb (diff) |
Move the WPACKET documentation comments to packet_locl.h
The PACKET documentation is already in packet_locl.h so it makes sense to
have the WPACKET documentation there as well.
Reviewed-by: Rich Salz <rsalz@openssl.org>
Diffstat (limited to 'ssl/packet_locl.h')
-rw-r--r-- | ssl/packet_locl.h | 91 |
1 files changed, 87 insertions, 4 deletions
diff --git a/ssl/packet_locl.h b/ssl/packet_locl.h index acbd966121..255a8a508a 100644 --- a/ssl/packet_locl.h +++ b/ssl/packet_locl.h @@ -583,43 +583,126 @@ struct wpacket_st { /* Number of bytes written so far */ size_t written; - /* - * Maximum number of bytes we will allow to be written to this WPACKET. - */ + /* Maximum number of bytes we will allow to be written to this WPACKET */ size_t maxsize; - /* Our sub-packets (always at least one if not closed) */ + /* Our sub-packets (always at least one if not finished) */ WPACKET_SUB *subs; }; /* Flags */ + +/* Default */ #define OPENSSL_WPACKET_FLAGS_NONE 0 + /* Error on WPACKET_close() if no data written to the WPACKET */ #define OPENSSL_WPACKET_FLAGS_NON_ZERO_LENGTH 1 + /* * Abandon all changes on WPACKET_close() if no data written to the WPACKET, * i.e. this does not write out a zero packet length */ #define OPENSSL_WPACKET_FLAGS_ABANDON_ON_ZERO_LENGTH 2 + +/* + * Initialise a WPACKET with the buffer in |buf|. The buffer must exist + * for the whole time that the WPACKET is being used. Additionally |lenbytes| of + * data is preallocated at the start of the buffer to store the length of the + * WPACKET once we know it. + */ int WPACKET_init_len(WPACKET *pkt, BUF_MEM *buf, size_t lenbytes); + +/* + * Same as WPACKET_init_len except there is no preallocation of the WPACKET + * length. + */ int WPACKET_init(WPACKET *pkt, BUF_MEM *buf); + +/* + * Set the flags to be applied to the current sub-packet + */ int WPACKET_set_flags(WPACKET *pkt, unsigned int flags); + +/* + * Set the WPACKET length, and the location for where we should write that + * length. Normally this will be at the start of the WPACKET, and therefore + * the WPACKET would have been initialised via WPACKET_init_len(). However there + * is the possibility that the length needs to be written to some other location + * other than the start of the WPACKET. In that case init via WPACKET_init() and + * then set the location for the length using this function. + */ int WPACKET_set_packet_len(WPACKET *pkt, unsigned char *packet_len, size_t lenbytes); + +/* + * Closes the most recent sub-packet. It also writes out the length of the + * packet to the required location (normally the start of the WPACKET) if + * appropriate. The top level WPACKET should be closed using WPACKET_finish() + * instead of this function. + */ int WPACKET_close(WPACKET *pkt); + +/* + * The same as WPACKET_close() but only for the top most WPACKET. Additionally + * frees memory resources for this WPACKET. + */ int WPACKET_finish(WPACKET *pkt); + +/* + * Initialise a new sub-packet. Additionally |lenbytes| of data is preallocated + * at the start of the sub-packet to store its length once we know it. + */ int WPACKET_start_sub_packet_len(WPACKET *pkt, size_t lenbytes); + +/* + * Same as WPACKET_start_sub_packet_len() except no bytes are pre-allocated for + * the sub-packet length. + */ int WPACKET_start_sub_packet(WPACKET *pkt); + +/* + * Allocate bytes in the WPACKET for the output. This reserves the bytes + * and counts them as "written", but doesn't actually do the writing. A pointer + * to the allocated bytes is stored in |*allocbytes|. + */ int WPACKET_allocate_bytes(WPACKET *pkt, size_t bytes, unsigned char **allocbytes); + +/* + * Write the value stored in |val| into the WPACKET. The value will consume + * |bytes| amount of storage. An error will occur if |val| cannot be + * accommodated in |bytes| storage, e.g. attempting to write the value 256 into + * 1 byte will fail. + */ int WPACKET_put_bytes(WPACKET *pkt, unsigned int val, size_t bytes); + +/* Set a maximum size that we will not allow the WPACKET to grow beyond */ int WPACKET_set_max_size(WPACKET *pkt, size_t maxsize); + +/* Copy |len| bytes of data from |*src| into the WPACKET. */ int WPACKET_memcpy(WPACKET *pkt, const void *src, size_t len); + +/* + * Copy |len| bytes of data from |*src| into the WPACKET and prefix with its + * length (consuming |lenbytes| of data for the length) + */ int WPACKET_sub_memcpy(WPACKET *pkt, const void *src, size_t len, size_t lenbytes); + +/* + * Return the total number of bytes written so far to the underlying buffer + * including any storage allocated for length bytes + */ int WPACKET_get_total_written(WPACKET *pkt, size_t *written); + +/* + * Returns the length of the current sub-packet. This excludes any bytes + * allocated for the length itself. + */ int WPACKET_get_length(WPACKET *pkt, size_t *len); + +/* Release resources in a WPACKET if a failure has occurred. */ void WPACKET_cleanup(WPACKET *pkt); # ifdef __cplusplus |