bencode.h File Reference

Provides routines for parsing and formating bencoded data. More...

#include <stdio.h>

Include dependency graph for bencode.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	bvalue
	bencoding value. More...

Functions
struct bvalue *	bvalue_new_dict (void)
	Allocate a dictionary value. More...
struct bvalue *	bvalue_new_list (void)
	Allocate a list value. More...
struct bvalue *	bvalue_new_integer (long long int i)
	Allocate an integer value. More...
struct bvalue *	bvalue_new_string (const unsigned char *s, size_t len)
	Allocate a string value. More...
struct bvalue *	bvalue_copy (const struct bvalue *val)
	Deep copy bencoding value. More...
void	bvalue_free (struct bvalue *val)
	Free bencoding value. More...
int	bvalue_list_append (struct bvalue *list, struct bvalue *val)
	Append value to a list. More...
int	bvalue_dict_set (struct bvalue *dict, const char *key, struct bvalue *val)
	Add a key-value pair to a dictionary. More...
const struct bvalue *	bvalue_dict_get (const struct bvalue *dict, const char *key)
	Get dictionary value. More...
const struct bvalue *	bvalue_list_get (const struct bvalue *list, size_t pos)
	Get list value. More...
const unsigned char *	bvalue_string (const struct bvalue *val, size_t *len)
	Get string value. More...
int	bvalue_integer (const struct bvalue *val, int *intval)
	Get integer (int) value. More...
int	bvalue_integer_l (const struct bvalue *val, long int *intval)
	Get integer (long int) value. More...
int	bvalue_integer_ll (const struct bvalue *val, long long int *intval)
	Get integer (long long int) value. More...
struct bvalue *	bdecode_file (FILE *stream)
	Parse bencoded file. More...
int	bencode_file (const struct bvalue *val, FILE *stream)
	bencode value to file. More...
struct bvalue *	bdecode_buf (const unsigned char *buf, size_t len)
	Parse bencoded string buffer. More...
int	bencode_buf (const struct bvalue *val, unsigned char *buf, size_t len)
	bencode value to a string buffer. More...
int	bencode_buf_alloc (const struct bvalue *val, unsigned char **bufp)
	Allocate and bencode value to a string buffer. More...

Detailed Description

Provides routines for parsing and formating bencoded data.

All BitTorrent specifications use a special data serialization format called bencoding. This API contains the tools necessary to parse and format bencoded data.

Function Documentation

struct bvalue* bdecode_buf	(	const unsigned char *	buf,
		size_t	len
	)

Parse bencoded string buffer.

Parameters

buf	string buffer to parse.
len	Length to parse.

Returns

Parsed value or NULL if parsing failed.

struct bvalue* bdecode_file

(

FILE *

stream

)

Parse bencoded file.

Parameters

stream

Stream to parse (FILE pointer).

Returns

Parsed value or NULL if parsing failed.

int bencode_buf	(	const struct bvalue *	val,
		unsigned char *	buf,
		size_t	len
	)

bencode value to a string buffer.

Parameters

val	Value to encode.
buf	Memory buffer to write encoded data to.
len	Length of the memory buffer.

Returns

number of characters written to stream or -1 if buf is not large enough.

int bencode_buf_alloc	(	const struct bvalue *	val,
		unsigned char **	bufp
	)

Allocate and bencode value to a string buffer.

This function is analog to bencode_buf, except it allocates a buffer large enough to hold the output. The buffered returned in bufp should be freed by the application when it is no longer needed.

Parameters

val	Value to encode.
bufp	Pointer to a location that will receive the address of the encoded data.

Returns

number of characters written to stream or -1 if an error occured.

int bencode_file	(	const struct bvalue *	val,
		FILE *	stream
	)

bencode value to file.

Parameters

val	Value to encode.
stream	Stream to write encoded data to.

Returns

number of characters written to stream or -1 if write failed.

struct bvalue* bvalue_copy

(

const struct bvalue *

val

)

Deep copy bencoding value.

Recursively copy val an all of it's children.

Parameters

val	The value to copy.

const struct bvalue* bvalue_dict_get	(	const struct bvalue *	dict,
		const char *	key
	)

Get dictionary value.

Lookup a value by key in a dictionary.

Parameters

dict	The dictionary value to get the value from. Must be of type BVALUE_DICTIONARY.
key	The key the value is set to in the dictionary.

Returns

The value or NULL if not found.

int bvalue_dict_set	(	struct bvalue *	dict,
		const char *	key,
		struct bvalue *	val
	)

Add a key-value pair to a dictionary.

Set key key to value val in dictionary value dict. dict must be of type BVALUE_DICTIONARY. If the key is already set in dict, the old value is simply freed and replaced.

Parameters

dict	The dictionary value to add the key-value pair to.
key	The key to set.
val	The value to corresponding to the key.

Returns

0 on success, -1 on memory allocation failure.

void bvalue_free

(

struct bvalue *

val

)

Free bencoding value.

Recursively free val and all of its children.

Parameters

val	The value to free.

int bvalue_integer	(	const struct bvalue *	val,
		int *	intval
	)

Get integer (int) value.

Returns the integer value of a value of type BVALUE_INTEGER.

Parameters

val	The integer value. Must be of type BVALUE_INTEGER.
intval	Pointer to an int that will receive the integer value.

Returns

0 on success, or -1 if val has the wrong type or in case of overflow.

int bvalue_integer_l	(	const struct bvalue *	val,
		long int *	intval
	)

Get integer (long int) value.

Returns the integer value of a value of type BVALUE_INTEGER.

Parameters

val	The integer value. Must be of type BVALUE_INTEGER.
intval	Pointer to an int that will receive the integer value.

Returns

0 on success, or -1 if val has the wrong type or in case of overflow.

int bvalue_integer_ll	(	const struct bvalue *	val,
		long long int *	intval
	)

Get integer (long long int) value.

Returns the integer value of a value of type BVALUE_INTEGER.

Parameters

val	The integer value. Must be of type BVALUE_INTEGER.
intval	Pointer to an int that will receive the integer value.

Returns

0 on success, or -1 if val has the wrong type or in case of overflow.

int bvalue_list_append	(	struct bvalue *	list,
		struct bvalue *	val
	)

Append value to a list.

Add val to the end of the list value list. list must be of type BVALUE_LIST.

Parameters

list	The list value to append to.
val	The value to append.

Returns

0 on success, -1 on memory allocation failure.

const struct bvalue* bvalue_list_get	(	const struct bvalue *	list,
		size_t	pos
	)

Get list value.

Get a value by position in a list.

Parameters

list	The list value to get the value from. Must be of type BVALUE_LIST.
pos	The position of the value in the list.

Returns

The value or NULL if pos is invalid.

struct bvalue* bvalue_new_dict

(

void

)

Allocate a dictionary value.

Builds a new empty dictionary value.

Returns

Pointer to newly allocated value, or NULL on allocation failure.

struct bvalue* bvalue_new_integer

(

long long int

i

)

Allocate an integer value.

Builds a new integer value and set it to i.

Parameters

i	Initial integer value.

Returns

Pointer to newly allocated value, or NULL on allocation failure.

struct bvalue* bvalue_new_list

(

void

)

Allocate a list value.

Builds a new empty list value.

Returns

Pointer to newly allocated value, or NULL on allocation failure.

struct bvalue* bvalue_new_string	(	const unsigned char *	s,
		size_t	len
	)

Allocate a string value.

Builds a new string value initially set to s. This function allocates its own copy of s, so the memory can be reused after the call. The internal string buffer is always null-terminated.

Parameters

s	pointer to the initial string value.
len	length (in bytes) of the intial string value.

Returns

Pointer to newly allocated value, or NULL on allocation failure.

const unsigned char* bvalue_string	(	const struct bvalue *	val,
		size_t *	len
	)

Get string value.

Get C string pointer from a value of type BVALUE_STRING. The return value is a pointer to the value's own internal storage. The returned string is always null-terminated so it can be used in printf-like functions. However, since it is designed to also store binary (non-ASCII) data, it can contain embedded zeroes. This function will optionnaly return the length of the string in len if not NULL.

Parameters

val	The string value. Must be of type BVALUE_STRING.
len	Optional pointer to an integer that will receive the length of the string.

Returns

C string or NULL if val is invalid.