include/event2/tag.h

0001 /*
0002  * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>
0003  * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
0004  *
0005  * Redistribution and use in source and binary forms, with or without
0006  * modification, are permitted provided that the following conditions
0007  * are met:
0008  * 1. Redistributions of source code must retain the above copyright
0009  *    notice, this list of conditions and the following disclaimer.
0010  * 2. Redistributions in binary form must reproduce the above copyright
0011  *    notice, this list of conditions and the following disclaimer in the
0012  *    documentation and/or other materials provided with the distribution.
0013  * 3. The name of the author may not be used to endorse or promote products
0014  *    derived from this software without specific prior written permission.
0015  *
0016  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
0017  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
0018  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
0019  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
0020  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
0021  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
0022  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
0023  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
0024  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
0025  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
0026  */
0027 #ifndef EVENT2_TAG_H_INCLUDED_
0028 #define EVENT2_TAG_H_INCLUDED_
0029
0030 /** @file event2/tag.h
0031
0032   Helper functions for reading and writing tagged data onto buffers.
0033
0034  */
0035
0036 #include <event2/visibility.h>
0037
0038 #ifdef __cplusplus
0039 extern "C" {
0040 #endif
0041
0042 #include <event2/event-config.h>
0043 #ifdef EVENT__HAVE_SYS_TYPES_H
0044 #include <sys/types.h>
0045 #endif
0046 #ifdef EVENT__HAVE_SYS_TIME_H
0047 #include <sys/time.h>
0048 #endif
0049
0050 /* For int types. */
0051 #include <event2/util.h>
0052
0053 struct evbuffer;
0054
0055 /*
0056  * Marshaling tagged data - We assume that all tags are inserted in their
0057  * numeric order - so that unknown tags will always be higher than the
0058  * known ones - and we can just ignore the end of an event buffer.
0059  */
0060
0061 EVENT2_EXPORT_SYMBOL
0062 void evtag_init(void);
0063
0064 /**
0065    Unmarshals the header and returns the length of the payload
0066
0067    @param evbuf the buffer from which to unmarshal data
0068    @param ptag a pointer in which the tag id is being stored
0069    @returns -1 on failure or the number of bytes in the remaining payload.
0070 */
0071 EVENT2_EXPORT_SYMBOL
0072 int evtag_unmarshal_header(struct evbuffer *evbuf, ev_uint32_t *ptag);
0073
0074 EVENT2_EXPORT_SYMBOL
0075 void evtag_marshal(struct evbuffer *evbuf, ev_uint32_t tag, const void *data,
0076     ev_uint32_t len);
0077 EVENT2_EXPORT_SYMBOL
0078 void evtag_marshal_buffer(struct evbuffer *evbuf, ev_uint32_t tag,
0079     struct evbuffer *data);
0080
0081 /**
0082   Encode an integer and store it in an evbuffer.
0083
0084   We encode integers by nybbles; the first nibble contains the number
0085   of significant nibbles - 1;  this allows us to encode up to 64-bit
0086   integers.  This function is byte-order independent.
0087
0088   @param evbuf evbuffer to store the encoded number
0089   @param number a 32-bit integer
0090  */
0091 EVENT2_EXPORT_SYMBOL
0092 void evtag_encode_int(struct evbuffer *evbuf, ev_uint32_t number);
0093 EVENT2_EXPORT_SYMBOL
0094 void evtag_encode_int64(struct evbuffer *evbuf, ev_uint64_t number);
0095
0096 EVENT2_EXPORT_SYMBOL
0097 void evtag_marshal_int(struct evbuffer *evbuf, ev_uint32_t tag,
0098     ev_uint32_t integer);
0099 EVENT2_EXPORT_SYMBOL
0100 void evtag_marshal_int64(struct evbuffer *evbuf, ev_uint32_t tag,
0101     ev_uint64_t integer);
0102
0103 EVENT2_EXPORT_SYMBOL
0104 void evtag_marshal_string(struct evbuffer *buf, ev_uint32_t tag,
0105     const char *string);
0106
0107 EVENT2_EXPORT_SYMBOL
0108 void evtag_marshal_timeval(struct evbuffer *evbuf, ev_uint32_t tag,
0109     struct timeval *tv);
0110
0111 EVENT2_EXPORT_SYMBOL
0112 int evtag_unmarshal(struct evbuffer *src, ev_uint32_t *ptag,
0113     struct evbuffer *dst);
0114 EVENT2_EXPORT_SYMBOL
0115 int evtag_peek(struct evbuffer *evbuf, ev_uint32_t *ptag);
0116 EVENT2_EXPORT_SYMBOL
0117 int evtag_peek_length(struct evbuffer *evbuf, ev_uint32_t *plength);
0118 EVENT2_EXPORT_SYMBOL
0119 int evtag_payload_length(struct evbuffer *evbuf, ev_uint32_t *plength);
0120 EVENT2_EXPORT_SYMBOL
0121 int evtag_consume(struct evbuffer *evbuf);
0122
0123 EVENT2_EXPORT_SYMBOL
0124 int evtag_unmarshal_int(struct evbuffer *evbuf, ev_uint32_t need_tag,
0125     ev_uint32_t *pinteger);
0126 EVENT2_EXPORT_SYMBOL
0127 int evtag_unmarshal_int64(struct evbuffer *evbuf, ev_uint32_t need_tag,
0128     ev_uint64_t *pinteger);
0129
0130 EVENT2_EXPORT_SYMBOL
0131 int evtag_unmarshal_fixed(struct evbuffer *src, ev_uint32_t need_tag,
0132     void *data, size_t len);
0133
0134 EVENT2_EXPORT_SYMBOL
0135 int evtag_unmarshal_string(struct evbuffer *evbuf, ev_uint32_t need_tag,
0136     char **pstring);
0137
0138 EVENT2_EXPORT_SYMBOL
0139 int evtag_unmarshal_timeval(struct evbuffer *evbuf, ev_uint32_t need_tag,
0140     struct timeval *ptv);
0141
0142 #ifdef __cplusplus
0143 }
0144 #endif
0145
0146 #endif /* EVENT2_TAG_H_INCLUDED_ */