/*
This file is part of GNUnet.
- (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009, 2012 Christian Grothoff (and other contributing authors)
+ (C) 2001-2013 Christian Grothoff (and other contributing authors)
GNUnet is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
- by the Free Software Foundation; either version 2, or (at your
+ by the Free Software Foundation; either version 3, or (at your
option) any later version.
GNUnet is distributed in the hope that it will be useful, but
*
* @param fancy_size human readable string (i.e. 1 MB)
* @param size set to the size in bytes
- * @return GNUNET_OK on success, GNUNET_SYSERR on error
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
*/
int
GNUNET_STRINGS_fancy_size_to_bytes (const char *fancy_size,
*
* @param fancy_time human readable string (i.e. 1 minute)
* @param rtime set to the relative time
- * @return GNUNET_OK on success, GNUNET_SYSERR on error
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
*/
int
GNUNET_STRINGS_fancy_time_to_relative (const char *fancy_time,
/**
+ * @ingroup time
* Convert a given fancy human-readable time to our internal
- * representation.
+ * representation. The human-readable time is expected to be
+ * in local time, whereas the returned value will be in UTC.
*
* @param fancy_time human readable string (i.e. %Y-%m-%d %H:%M:%S)
* @param atime set to the absolute time
- * @return GNUNET_OK on success, GNUNET_SYSERR on error
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
*/
int
GNUNET_STRINGS_fancy_time_to_absolute (const char *fancy_time,
* Convert the len characters long character sequence
* given in input that is in the given input charset
* to a string in given output charset.
+ *
+ * @param input input string
+ * @param len number of bytes in @a input
+ * @param input_charset character set used for @a input
+ * @param output_charset desired character set for the return value
* @return the converted string (0-terminated),
* if conversion fails, a copy of the orignal
* string is returned.
* to UTF-8.
*
* @param input the input string (not necessarily 0-terminated)
- * @param len the number of bytes in the input
+ * @param len the number of bytes in the @a input
* @param charset character set to convert from
* @return the converted string (0-terminated)
*/
char *
-GNUNET_STRINGS_to_utf8 (const char *input,
- size_t len,
+GNUNET_STRINGS_to_utf8 (const char *input,
+ size_t len,
const char *charset);
/**
* Convert the len bytes-long UTF-8 string
* given in input to the given charset.
-
+ *
+ * @param input the input string (not necessarily 0-terminated)
+ * @param len the number of bytes in the @a input
+ * @param charset character set to convert to
* @return the converted string (0-terminated),
* if conversion fails, a copy of the orignal
* string is returned.
*/
char *
-GNUNET_STRINGS_from_utf8 (const char *input,
- size_t len,
+GNUNET_STRINGS_from_utf8 (const char *input,
+ size_t len,
const char *charset);
/**
- * Convert the utf-8 input string to lowercase
- * Output needs to be allocated appropriately
+ * Convert the utf-8 input string to lower case.
+ * Output needs to be allocated appropriately.
*
* @param input input string
* @param output output buffer
*/
void
-GNUNET_STRINGS_utf8_tolower (const char* input,
- char** output);
+GNUNET_STRINGS_utf8_tolower (const char *input,
+ char *output);
/**
- * Convert the utf-8 input string to lowercase
- * Output needs to be allocated appropriately
+ * Convert the utf-8 input string to upper case.
+ * Output needs to be allocated appropriately.
*
* @param input input string
* @param output output buffer
*/
void
-GNUNET_STRINGS_utf8_toupper (const char* input,
- char** output);
+GNUNET_STRINGS_utf8_toupper (const char *input,
+ char *output);
/**
* (or number of bytes that would have been written)
*/
size_t
-GNUNET_STRINGS_buffer_fill (char *buffer,
- size_t size,
- unsigned int count,
+GNUNET_STRINGS_buffer_fill (char *buffer,
+ size_t size,
+ unsigned int count,
...);
* to the locations of the respective strings in the buffer.
*
* @param buffer the buffer to parse
- * @param size size of the buffer
+ * @param size size of the @a buffer
* @param count number of strings to locate
* @param ... pointers to where to store the strings
* @return offset of the character after the last 0-termination
* in the buffer, or 0 on error.
*/
unsigned int
-GNUNET_STRINGS_buffer_tokenize (const char *buffer, size_t size,
+GNUNET_STRINGS_buffer_tokenize (const char *buffer,
+ size_t size,
unsigned int count, ...);
/**
- * "asctime", except for GNUnet time.
- * This is one of the very few calls in the entire API that is
- * NOT reentrant!
+ * @ingroup time
+ * Like `asctime`, except for GNUnet time. Converts a GNUnet internal
+ * absolute time (which is in UTC) to a string in local time.
+ * Note that the returned value will be overwritten if this function
+ * is called again.
*
* @param t the absolute time to convert
- * @return timestamp in human-readable form
+ * @return timestamp in human-readable form in local time
*/
const char *
GNUNET_STRINGS_absolute_time_to_string (struct GNUNET_TIME_Absolute t);
/**
+ * @ingroup time
* Give relative time in human-readable fancy format.
* This is one of the very few calls in the entire API that is
- * NOT reentrant!
+ * NOT reentrant!
*
* @param delta time in milli seconds
* @param do_round are we allowed to round a bit?
* @return pointer to the next byte in 'out' or NULL on error.
*/
char *
-GNUNET_STRINGS_data_to_string (const unsigned char *data,
+GNUNET_STRINGS_data_to_string (const void *data,
size_t size,
- char *out,
+ char *out,
size_t out_size);
* @param enc the encoding
* @param enclen number of characters in 'enc' (without 0-terminator, which can be missing)
* @param out location where to store the decoded data
- * @param out_size sizeof the output buffer
- * @return GNUNET_OK on success, GNUNET_SYSERR if result has the wrong encoding
+ * @param out_size size of the output buffer @a out
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
*/
int
-GNUNET_STRINGS_string_to_data (const char *enc,
+GNUNET_STRINGS_string_to_data (const char *enc,
size_t enclen,
- unsigned char *out,
+ void *out,
size_t out_size);
* part of the URI will be stored. Can be NULL. Points to the same block
* of memory as 'path', and thus must not be freed. Might point to '\0',
* if path part is zero-length.
- * @return GNUNET_YES if it's an URI, GNUNET_NO otherwise. If 'path' is not
+ * @return #GNUNET_YES if it's an URI, #GNUNET_NO otherwise. If 'path' is not
* an URI, '* scheme_part' and '*path_part' will remain unchanged
* (if they weren't NULL).
*/
int
-GNUNET_STRINGS_parse_uri (const char *path,
+GNUNET_STRINGS_parse_uri (const char *path,
char **scheme_part,
const char **path_part);
* Check whether filename is absolute or not, and if it's an URI
*
* @param filename filename to check
- * @param can_be_uri GNUNET_YES to check for being URI, GNUNET_NO - to
+ * @param can_be_uri #GNUNET_YES to check for being URI, #GNUNET_NO - to
* assume it's not URI
- * @param r_is_uri a pointer to an int that is set to GNUNET_YES if 'filename'
+ * @param r_is_uri a pointer to an int that is set to #GNUNET_YES if 'filename'
* is URI and to GNUNET_NO otherwise. Can be NULL. If 'can_be_uri' is
- * not GNUNET_YES, *r_is_uri is set to GNUNET_NO.
+ * not #GNUNET_YES, *r_is_uri is set to #GNUNET_NO.
* @param r_uri_scheme a pointer to a char * that is set to a pointer to URI scheme.
* The string is allocated by the function, and should be freed with
* GNUNET_free (). Can be NULL.
- * @return GNUNET_YES if 'filename' is absolute, GNUNET_NO otherwise.
+ * @return #GNUNET_YES if 'filename' is absolute, #GNUNET_NO otherwise.
*/
int
-GNUNET_STRINGS_path_is_absolute (const char *filename,
+GNUNET_STRINGS_path_is_absolute (const char *filename,
int can_be_uri,
- int *r_is_uri,
+ int *r_is_uri,
char **r_uri_scheme);
/**
* Check that the path is an absolute path.
- */
+ */
GNUNET_STRINGS_CHECK_IS_ABSOLUTE = 0x00000008
};
/**
- * Perform checks on 'filename'. FIXME: some duplication with
+ * Perform checks on @a filename. FIXME: some duplication with
* "GNUNET_DISK_"-APIs. We should unify those.
- *
+ *
* @param filename file to check
* @param checks checks to perform
* @return GNUNET_YES if all checks pass, GNUNET_NO if at least one of them
/**
- * Tries to convert 'zt_addr' string to an IPv6 address.
+ * Tries to convert @a zt_addr string to an IPv6 address.
* The string is expected to have the format "[ABCD::01]:80".
- *
+ *
* @param zt_addr 0-terminated string. May be mangled by the function.
* @param addrlen length of zt_addr (not counting 0-terminator).
* @param r_buf a buffer to fill. Initially gets filled with zeroes,
* then its sin6_port, sin6_family and sin6_addr are set appropriately.
- * @return GNUNET_OK if conversion succeded. GNUNET_SYSERR otherwise, in which
+ * @return #GNUNET_OK if conversion succeded. #GNUNET_SYSERR otherwise, in which
* case the contents of r_buf are undefined.
*/
int
-GNUNET_STRINGS_to_address_ipv6 (const char *zt_addr,
+GNUNET_STRINGS_to_address_ipv6 (const char *zt_addr,
uint16_t addrlen,
struct sockaddr_in6 *r_buf);
/**
- * Tries to convert 'zt_addr' string to an IPv4 address.
+ * Tries to convert @a zt_addr string to an IPv4 address.
* The string is expected to have the format "1.2.3.4:80".
- *
+ *
* @param zt_addr 0-terminated string. May be mangled by the function.
* @param addrlen length of zt_addr (not counting 0-terminator).
* @param r_buf a buffer to fill.
- * @return GNUNET_OK if conversion succeded. GNUNET_SYSERR otherwise, in which case
+ * @return #GNUNET_OK if conversion succeded. #GNUNET_SYSERR otherwise, in which case
* the contents of r_buf are undefined.
*/
int
-GNUNET_STRINGS_to_address_ipv4 (const char *zt_addr,
+GNUNET_STRINGS_to_address_ipv4 (const char *zt_addr,
uint16_t addrlen,
struct sockaddr_in *r_buf);
/**
- * Tries to convert 'addr' string to an IP (v4 or v6) address.
+ * Tries to convert @a addr string to an IP (v4 or v6) address.
* Will automatically decide whether to treat 'addr' as v4 or v6 address.
- *
+ *
* @param addr a string, may not be 0-terminated.
- * @param addrlen number of bytes in addr (if addr is 0-terminated,
+ * @param addrlen number of bytes in @a addr (if addr is 0-terminated,
* 0-terminator should not be counted towards addrlen).
* @param r_buf a buffer to fill.
- * @return GNUNET_OK if conversion succeded. GNUNET_SYSERR otherwise, in which
+ * @return #GNUNET_OK if conversion succeded. #GNUNET_SYSERR otherwise, in which
* case the contents of r_buf are undefined.
*/
int
/**
- * Returns utf-8 encoded arguments.
- * Does nothing (returns a copy of argc and argv) on any platform
- * other than W32.
- * Returned argv has u8argv[u8argc] == NULL.
- * Returned argv is a single memory block, and can be freed with a single
- * GNUNET_free () call.
+ * Returns utf-8 encoded arguments. Does nothing (returns a copy of
+ * @a argc and @a argv) on any platform other than W32. Returned @a
+ * argv has `u8argv[u8argc] == NULL`. Returned @a argv is a single
+ * memory block, and can be freed with a single GNUNET_free() call.
*
* @param argc argc (as given by main())
* @param argv argv (as given by main())
* @param u8argc a location to store new argc in (though it's th same as argc)
* @param u8argv a location to store new argv in
- * @return GNUNET_OK on success, GNUNET_SYSERR on failure
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
*/
int
-GNUNET_STRINGS_get_utf8_args (int argc,
- char *const *argv,
+GNUNET_STRINGS_get_utf8_args (int argc,
+ char *const *argv,
int *u8argc,
char *const **u8argv);
+/* ***************** IPv4/IPv6 parsing ****************** */
+
+struct GNUNET_STRINGS_PortPolicy
+{
+
+ /**
+ * Starting port range (0 if none given).
+ */
+ uint16_t start_port;
+
+ /**
+ * End of port range (0 if none given).
+ */
+ uint16_t end_port;
+
+ /**
+ * #GNUNET_YES if the port range should be negated
+ * ("!" in policy).
+ */
+ int negate_portrange;
+
+};
+
+
+/**
+ * @brief IPV4 network in CIDR notation.
+ */
+struct GNUNET_STRINGS_IPv4NetworkPolicy
+{
+ /**
+ * IPv4 address.
+ */
+ struct in_addr network;
+
+ /**
+ * IPv4 netmask.
+ */
+ struct in_addr netmask;
+
+ /**
+ * Policy for port access.
+ */
+ struct GNUNET_STRINGS_PortPolicy pp;
+
+};
+
+
+/**
+ * @brief network in CIDR notation for IPV6.
+ */
+struct GNUNET_STRINGS_IPv6NetworkPolicy
+{
+ /**
+ * IPv6 address.
+ */
+ struct in6_addr network;
+
+ /**
+ * IPv6 netmask.
+ */
+ struct in6_addr netmask;
+
+ /**
+ * Policy for port access.
+ */
+ struct GNUNET_STRINGS_PortPolicy pp;
+
+};
+
+
+/**
+ * Parse an IPv4 network policy. The argument specifies a list of
+ * subnets. The format is <tt>(network[/netmask][:[!]SPORT-DPORT];)*</tt>
+ * (no whitespace, must be terminated with a semicolon). The network
+ * must be given in dotted-decimal notation. The netmask can be given
+ * in CIDR notation (/16) or in dotted-decimal (/255.255.0.0).
+ *
+ * @param routeListX a string specifying the IPv4 subnets
+ * @return the converted list, terminated with all zeros;
+ * NULL if the synatx is flawed
+ */
+struct GNUNET_STRINGS_IPv4NetworkPolicy *
+GNUNET_STRINGS_parse_ipv4_policy (const char *routeListX);
+
+
+/**
+ * Parse an IPv6 network policy. The argument specifies a list of
+ * subnets. The format is <tt>(network[/netmask[:[!]SPORT[-DPORT]]];)*</tt>
+ * (no whitespace, must be terminated with a semicolon). The network
+ * must be given in colon-hex notation. The netmask must be given in
+ * CIDR notation (/16) or can be omitted to specify a single host.
+ * Note that the netmask is mandatory if ports are specified.
+ *
+ * @param routeListX a string specifying the policy
+ * @return the converted list, 0-terminated, NULL if the synatx is flawed
+ */
+struct GNUNET_STRINGS_IPv6NetworkPolicy *
+GNUNET_STRINGS_parse_ipv6_policy (const char *routeListX);
+
+
+
#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
projects / oweals / gnunet.git / blobdiff