base utils
[utils]

Base definitions and functions of GPAC. More...

Modules
	Time tools
	System time and CPU functions.
Defines
#define	gf_stringizer(x)
	Stringizer.
#define	GF_SAFEALLOC(__ptr, __struct)
	Memory allocation for a structure.
#define	GF_SAFE_ALLOC_N(__ptr, __n, __struct)
	Memory allocation for an array of n structs.
Typedefs
typedef Bool(*	gf_enum_dir_item )(void *cbck, char *item_name, char *item_path)
	Directory Enumeration Callback.
typedef void(*	gf_on_progress_cbk )(const void *cbck, const char *title, u64 done, u64 total)
	Progress Callback.
Functions
const char *	gpac_features ()
	4CC Formatting
const char *	gf_4cc_to_str (u32 type)
	4CC Printing
int	gf_asprintf (char **buffer, const char *fmt,...)
	asprintf() portable implementation
size_t	gf_fwrite (const void *ptr, size_t size, size_t nmemb, FILE *stream)
	file writing helper
FILE *	gf_f64_open (const char *file_name, const char *mode)
	large file opening
u64	gf_f64_tell (FILE *f)
	large file position query
u64	gf_f64_seek (FILE *f, s64 pos, s32 whence)
	large file seeking
void	gf_rand_init (Bool Reset)
	PseudoRandom Integer Generation Initialization.
u32	gf_rand ()
	PseudoRandom Integer Generation.
void	gf_get_user_name (char *buf, u32 buf_size)
	user name
GF_Err	gf_enum_directory (const char *dir, Bool enum_directory, gf_enum_dir_item enum_dir, void *cbck, const char *filter)
	Directory enumeration.
GF_Err	gf_delete_file (const char *fileName)
	File Deletion.
GF_Err	gf_move_file (const char *fileName, const char *newFileName)
	File Move.
FILE *	gf_temp_file_new ()
	Temporary File Creation.
u64	gf_file_modification_time (const char *filename)
	File Modification Time.
void	gf_set_progress (const char *title, u64 done, u64 total)
	Progress formatting.
void	gf_set_progress_callback (void *user_cbk, gf_on_progress_cbk prog_cbk)
	Progress overwriting.
Bool	gf_prompt_has_input ()
	Prompt checking.
char	gf_prompt_get_char ()
	Prompt character flush.
void	gf_prompt_set_echo_off (Bool echo_off)
	turns prompt echo on/off

---

Detailed Description

This section documents some very basic functions and core definitions of the GPAC framework.

---

Define Documentation

#define gf_stringizer

(

x

)

Macro transforming its input name into a string

#define GF_SAFEALLOC	(	__ptr,
		__struct		)

Macro allocating memory and zero-ing it

#define GF_SAFE_ALLOC_N	(	__ptr,
		__n,
		__struct		)

Macro allocating memory for n structures and zero-ing it

---

Typedef Documentation

typedef Bool(* gf_enum_dir_item)(void *cbck, char *item_name, char *item_path)

The gf_enum_dir_item type is the type for the callback of the gf_enum_directory function

Parameters:

	cbck	Opaque user data.
	item_name	File or directory name.
	item_path	File or directory full path and name from filesystem root.

Returns:

1 to abort enumeration, 0 to continue enumeration.

typedef void(* gf_on_progress_cbk)(const void *cbck, const char *title, u64 done, u64 total)

The gf_on_progress_cbk type is the type for the callback of the gf_set_progress_callback function

Parameters:

	cbck	Opaque user data.
	title	preogress title.
	done	Current amount performed of the action
	total	Total amount of the action.

---

Function Documentation

const char* gpac_features

(

)

Macro formating a 4-character code (or 4CC) "abcd" as 0xAABBCCDD

GPAC feature list returns the list of features enabled/disabled in this GPAC build.

const char* gf_4cc_to_str

(

u32

type

)

returns a 4CC printable form

int gf_asprintf	(	char **	buffer,
		const char *	fmt,
			...
	)

similar to sprintf, except it allows the string on the

Note:

asprintf implementation for windows

size_t gf_fwrite	(	const void *	ptr,
		size_t	size,
		size_t	nmemb,
		FILE *	stream
	)

Wrapper to properly handle calls to fwrite() Ensures proper error handling is invoked when it fails.

Returns:

Same as gf_fwrite

FILE* gf_f64_open	(	const char *	file_name,
		const char *	mode
	)

Opens a large file (>4GB)

Parameters:

	file_name	Same semantics as gf_f64_open
	mode	Same semantics as gf_f64_open

Returns:

stream handle of the file object

Note:

You only need to call this function if you're suspecting the file to be a large one (usually only media files), otherwise use regular stdio.

u64 gf_f64_tell

(

FILE *

f

)

Queries the current read/write position in a large file

Parameters:

f

Same semantics as ftell

Returns:

position in the file

Note:

You only need to call this function if you're suspecting the file to be a large one (usually only media files), otherwise use regular stdio.

u64 gf_f64_seek	(	FILE *	f,
		s64	pos,
		s32	whence
	)

Seeks the current read/write position in a large file

Parameters:

	f	Same semantics as gf_f64_seek
	pos	Same semantics as gf_f64_seek
	whence	Same semantics as gf_f64_seek

Returns:

new position in the file

Note:

You only need to call this function if you're suspecting the file to be a large one (usually only media files), otherwise use regular stdio.

void gf_rand_init

(

Bool

Reset

)

Sets the starting point for generating a series of pseudorandom integers.

Parameters:

Reset

Re-initializes the random number generator

u32 gf_rand

(

)

Returns a pseudorandom integer.

void gf_get_user_name	(	char *	buf,
		u32	buf_size
	)

Gets current user (login) name.

GF_Err gf_enum_directory	(	const char *	dir,
		Bool	enum_directory,
		gf_enum_dir_item	enum_dir,
		void *	cbck,
		const char *	filter
	)

Enumerates a directory content. Feedback is provided by the enum_dir_item function

Parameters:

	dir	Directory to enumerate
	enum_directory	If set, only directories will be enumerated, otherwise only files are.
	enum_dir	gf_enum_dir_item callback function for enumeration.
	cbck	Opaque user data passed to callback function.
	filter	optional filter for file extensions. If a file extension without the dot '.' character is not found in the filter the file will be skipped.

GF_Err gf_delete_file

(

const char *

fileName

)

Deletes a file from the disk.

Parameters:

fileName

absolute name of the file or name relative to the current working directory.

GF_Err gf_move_file	(	const char *	fileName,
		const char *	newFileName
	)

Moves or renames a file or directory.

Parameters:

	fileName	absolute path of the file / directory to move or rename
	newFileName	absolute new path/name of the file / directory

FILE* gf_temp_file_new

(

)

Creates a new temporary file in binary mode

Returns:

stream handle to the new file ressoucre

u64 gf_file_modification_time

(

const char *

filename

)

Returns the modification time of the given file. The exact meaning of this value is system dependent

Parameters:

filename

file to check

Returns:

modification time of the file

void gf_set_progress	(	const char *	title,
		u64	done,
		u64	total
	)

Signals progress in GPAC's operations. Note that progress signaling with this function is not thread-safe, the main purpose is to use it for authoring tools only.

Parameters:

	title	title string of the progress, or NULL for no progress
	done	Current amount performed of the action.
	total	Total amount of the action.

void gf_set_progress_callback	(	void *	user_cbk,
		gf_on_progress_cbk	prog_cbk
	)

Iverwrites the progress signaling function by a user-defined one.

Parameters:

	user_cbk	Opaque user data
	prog_cbk	new callback function to use. Passing NULL restore default GPAC stderr notification.

Bool gf_prompt_has_input

(

)

Checks if a character is pending in the prompt buffer.

Returns:

1 if a character is ready to be fetched, 0 otherwise.

Note:

Function not available under WindowsCE nor SymbianOS

char gf_prompt_get_char

(

)

Returns the current character entered at prompt if any.

Returns:

value of the character.

Note:

Function not available under WindowsCE nor SymbianOS

void gf_prompt_set_echo_off

(

Bool

echo_off

)

Turns the prompt character echo on/off - this is usefull when entering passwords.

Parameters:

echo_off

indicates whether echo should be turned on or off.

Note:

Function not available under WindowsCE nor SymbianOS