octstr.h

The Kannel Open Source WAP and SMS gateway works as both an SMS gateway, for implementing keyword b

 * Return the start position (index) of 'needle' in 'haystack'.
 * Return -1 if not found.
 */
int octstr_search(const Octstr *haystack, const Octstr *needle, long pos);


/*
 * Like octstr_search, but ignores 8-bit byte case.
 */
int octstr_case_search(const Octstr *haystack, const Octstr *needle, long pos);

/*
 * Like octstr_case_search, but searchs only first n octets.
 */
int octstr_case_nsearch(const Octstr *haystack, const Octstr *needle, long pos, long n);

/*
 * Write contents of octet string to a file, in human readable form. 
 * Return -1 for error, 0 for OK. Octets that are not printable characters
 * are printed using C-style escape notation.
 */
int octstr_pretty_print(FILE *f, Octstr *ostr);


/*
 * Write contents of octet string to a socket. Return -1 for error, 0 for OK.
 */
int octstr_write_to_socket(int socket, Octstr *ostr);

/*
 * Write contents of octet string starting at 'from' to a
 * non-blocking file descriptor.
 * Return the number of octets written.  Return -1 for error.
 * It is possible for this function to write only part of the octstr.
 */
long octstr_write_data(Octstr *ostr, int fd, long from);

/*
 * Read available data from socket and return it as an octstr.
 * Block if no data is available.  If a lot of data is available,
 * read only up to an internal limit.
 * Return -1 for error.
 */
int octstr_append_from_socket(Octstr *ostr, int socket);

/*
 * Insert one octet string into another. `pos' gives the position
 * in `ostr1' where `ostr2' should be inserted.
 */
void octstr_insert(Octstr *ostr1, const Octstr *ostr2, long pos);


/*
 * Insert characters from C array into an octet string. `pos' 
 * gives the position in `ostr' where `data' should be inserted. `len'
 * gives the number of characters in `data'.
 * If the given `pos' is greater than the length of the input octet string,
 * it is set to that length, resulting in an append.
 */
void octstr_insert_data(Octstr *ostr, long pos, const char *data, long len);

/*
 * Similar as previous, expect that now a single character is inserted.
 */
void octstr_insert_char(Octstr *ostr, long pos, const char c);


/*
 * Append characters from C array at the tail of an octet string.
 */
void octstr_append_data(Octstr *ostr, const char *data, long len);


/*
 * Append a second octstr to the first.
 */
void octstr_append(Octstr *ostr1, const Octstr *ostr2);


/*
 * Append a normal C string at the tail of an octet string.
 */
void octstr_append_cstr(Octstr *ostr, const char *cstr);


/*
 * Append a single character at the tail of an octet string.
 */
void octstr_append_char(Octstr *ostr, int ch);


/*
 * Truncate octet string at `new_len'. If new_len is same or more
 * than current, do nothing.
 */
void octstr_truncate(Octstr *ostr, int new_len);


/*
 * Strip white space from start and end of a octet string.
 */
void octstr_strip_blanks(Octstr *ostr);

/*
 * Strip CR and LF from start and end of a octet string.
 */
void octstr_strip_crlfs(Octstr *ostr);

/*
 * Strip non-alphanums from start and end of a octet string.
 */
void octstr_strip_nonalphanums(Octstr *ostr);


/*
 * Shrink consecutive white space characters into one space.
 */
void octstr_shrink_blanks(Octstr *ostr);


/*
 * Delete part of an octet string.
 */
void octstr_delete(Octstr *ostr1, long pos, long len);


/*
 * Read the contents of a named file to an octet string. Return pointer to
 * octet string.
 */
Octstr *octstr_read_file(const char *filename);


/*
 * Read the contents of a file descriptor pipe to an octet string. 
 * Return pointer to octet string.
 */
Octstr *octstr_read_pipe(FILE *f);


/*
 * Split an octet string into words at whitespace, and return a list
 * containing the new octet strings.
 */
List *octstr_split_words(const Octstr *ostr);


/*
 * Split an octet string into substrings at every occurence of `sep'.
 * Return List with the substrings.
 */
List *octstr_split(const Octstr *os, const Octstr *sep);


/*
 * Compare two octet strings in a manner suitable for list_search.
 */
int octstr_item_match(void *item, void *pattern);


/*
 * Same as above, except compares bytes without case sensitivity
 */
int octstr_item_case_match(void *item, void *pattern);


/*
 * Print debugging information about octet string.
 */
void octstr_dump(const Octstr *ostr, int level);


/*
 * Write the contents of an octet string to the debug log.
 * Keep it on one line if the octet string is short and printable,
 * otherwise use a hex dump.
 */
void octstr_dump_short(Octstr *ostr, int level, const char *name);


/*
 * decode url-encoded octstr in-place.
 * Return 0 if all went fine, or -1 if there was some garbage
 */
int octstr_url_decode(Octstr *ostr);


/*
 * URL encode the argument string in place.
 */
void octstr_url_encode(Octstr *ostr);


/*
 * Treat the octstr as an unsigned array of bits, most significant bit
 * first, and return the indicated bit range as an integer.  numbits
 * must not be larger than 32.  Bits beyond the end of the string will
 * be read as 0.
 */
long octstr_get_bits(Octstr *ostr, long bitpos, int numbits);


/*
 * Treat the octstr as an unsigned array of bits, most significant bit
 * first, and set the indicated bit range to the given value.  numbits
 * must not be larger than 32.  The value must fit in that number of bits.
 * The string will be extended with 0-valued octets as necessary to hold
 * the indicated bit range.
 */
void octstr_set_bits(Octstr *ostr, long bitpos, int numbits, 
    	    	     unsigned long value);


/* 
 * Encode value in WSP's uintvar format, and append it to the octstr
 */
void octstr_append_uintvar(Octstr *ostr, unsigned long value);


/* 
 * Decode a value in WSP's uintvar format at position pos of the octstr,
 * and put the result in *value.  Return the position after the uintvar.
 * Return -1 if there is not a valid uintvar at pos.
 */
long octstr_extract_uintvar(Octstr *ostr, unsigned long *value, long pos);


/*
 * Append the decimal representation of the given value to ostr 
 */
void octstr_append_decimal(Octstr *ostr, long value);


/*
 * Create a new octet string based on a printf-like (but not identical)
 * format string, and a list of other arguments. The format string is
 * a C string for convenience, but this may change later.
 *
 * The syntax for the format string is as follows:
 *
 *	% [-] [0] [width] [. prec] [type] conversion
 *
 * where [] denotes optional parts and the various parts have the
 * following meanings:
 *
 *	-	add padding to the right, instead of the left of the field
 *
 *	0	pad with zeroes, not spaces
 *
 *	width	minimum output width; non-negative integer or '*', indicating
 *		that the next argument is an int and gives the width
 *
 *	.	a dot to indicate that precision follows
 *
 *	prec	precision: maximum length of strings, maximum number of
 *		decimals for floating point numbers; non-negative integer
 *		or '*' indicating that the next argument is an int and
 *		gives the precision
 *
 *	type	type of integer argument: either h (for short int) or 
 *		l (for long int); may only be used with conversion 'd'
 *
 *	conversion
 *		how the field is to be converted, also implicitly defines
 *		the type of the next argument; one of
 *
 *			d	int (unless type says otherwise)
 *				output as a decimal integer
 *
 *			e, f, g	double
 *				output in various formats of floating
 *				point, see printf(3) for details
 *
 *			s	char *
 *				output as character string
 *
 *			S	Octstr *
 *				output as character string, except '\0'
 *				inside the string is included in the
 *				output
 *
 *			E	Octstr *
 *				output as character string, except that
 *				contents are URL-encoded when need to. Note
 *				that trunctae is done afterwards and can
 *				cut escape '%EE' in half
 *
 *			H	Octstr *
 *				output as character string, except that
 *				contents are HEX-encoded in uppercase
 */
Octstr *octstr_format(const char *fmt, ...);

/*
 * Like octstr_format, but takes the argument list as a va_list.
 */
Octstr *octstr_format_valist_real(const char *fmt, va_list args);
#define octstr_format_valist(fmt, args) gw_claim_area(octstr_format_valist_real(fmt, args))

/*
 * Like octstr_format, but appends output to an existing octet
 * string, instead of creating a new one.
 */
void octstr_format_append(Octstr *os, const char *fmt, ...);


/*
 * Compute a hash key value for an octet string by adding all the 
 * octets together.
 */
unsigned long octstr_hash_key(Octstr *ostr);

/*
 * return an Octstr encoded in charset named tocode created from the data
 * in the Octstr orig that is encoded in the charset fromcode.
 */
int octstr_recode(Octstr *tocode, Octstr *fromcode, Octstr *orig);

/*
 * Strip all occurence of char ch from start of Octstr
 */
void octstr_strip_char(Octstr *text, char ch);

/*
 * Check if ostr is numeric
 */
int octstr_isnum(Octstr *ostr1);

/*
 * Replace all occurences of needle with repl within haystack
 */
void octstr_replace(Octstr *haystack, Octstr *needle, Octstr *repl);

/*
 * Symbolize hex string '78797a' becomes '%78%79%7a'
 */
int octstr_symbolize(Octstr *ostr);

/*
 * Remove all occurrences of 'needle' within 'haystack'.
 */
void octstr_delete_matching(Octstr *haystack, Octstr *needle);

/*
 * Return 1, if octstr 'os' contains only hex chars, 0 otherwise.
 */
int octstr_is_all_hex(Octstr *os);                                                    
                                                    
/*
 * make data HTML safe by converting appropriate characters to HTML entities.
 * conversion is done in place
 */
void octstr_convert_to_html_entities(Octstr* input);

/*
 * convert HTML safe data back to binary data by replacing HTML entities with their
 * respective character values.
 * conversion is done in place
 */
void octstr_convert_from_html_entities(Octstr* input);

#endif