WebSVN – HelenOS – Diff – /branches/network/uspace/srv/net/structures/measured_strings.h



/*
 * Copyright (c) 2009 Lukas Mejdrech
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:

/** @addtogroup net
 *  @{
 */
 
/** @file
 *  Character string with measured length.
 *  The structure has been designed for serialization of character strings between modules.
 */
 
#ifndef __MEASURED_STRINGS_H__
#define __MEASURED_STRINGS_H__
 
/** Type definition of the character string with measured length.
 *  @see measured_string
 */
typedef struct measured_string  measured_string_t;
 
/** Type definition of the character string with measured length pointer.
 *  @see measured_string
 */
typedef measured_string_t *     measured_string_ref;
 
/** Character string with measured length.
 *  This structure has been designed for serialization of character strings between modules.
 */
struct  measured_string{
 
    /** Character string data.
     */
    char *  value;
 
    /** Character string length.
     */
    size_t  length;
};
 
/** Creates a&nbsp;new measured string bundled with a&nbsp;copy of the given string itself as one memory block.
 *  If the measured string is being freed, whole memory block is freed.
 *  The measured string should be used only as a&nbsp;constant.
 *  @param string The initial character string to be stored. Input parameter.
 *  @param length The length of the given string without the terminating zero ('/0') character. If the length is zero (0), the actual length is computed. The given length is used and appended with the terminating zero ('\\0') character otherwise. Input parameter.
 *  @returns The new bundled character string with measured length.
 *  @returns NULL if there is not enough memory left.
 */
measured_string_ref measured_string_create_bulk( const char * string, size_t length );
 
/** Receives a&nbsp;measured strings array from a&nbsp;calling module.
 *  Creates the array and the data memory blocks.

 *  @returns EOK on success.
 *  @returns EINVAL if the strings or data parameter is NULL.
 *  @returns EINVAL if the count parameter is zero (0).
 *  @returns EINVAL if the sent array differs in size.
 *  @returns EINVAL if there is inconsistency in sent measured strings' lengths (should not occur).
 *  @returns ENOMEM if there is not enough memory left.
 *  @returns Other error codes as defined for the ipc_data_write_finalize() function.
 */
int measured_strings_receive( measured_string_ref * strings, char ** data, size_t count );
 
/** Replies the given measured strings array to a&nbsp;calling module.

 *  @param count The size of the measured strings array. Input parameter.
 *  @returns EOK on success.
 *  @returns EINVAL if the strings or data parameter is NULL.
 *  @returns EINVAL if the phone or count parameter is not positive (<=0).
 *  @returns EINVAL if the sent array differs in size.
 *  @returns ENOMEM if there is not enough memory left.
 *  @returns Other error codes as defined for the ipc_data_read_start() function.
 */
int measured_strings_return( int phone, measured_string_ref * strings, char ** data, size_t count );
 
/** Sends the given measured strings array to another module.

Rev 3886	Rev 3912
Line 1...	Line 1...
1	/*	1	/*
2	* Copyright (c) 2008 Lukas Mejdrech	2	* Copyright (c) 2009 Lukas Mejdrech
3	* All rights reserved.	3	* All rights reserved.
4	*	4	*
5	* Redistribution and use in source and binary forms, with or without	5	* Redistribution and use in source and binary forms, with or without
6	* modification, are permitted provided that the following conditions	6	* modification, are permitted provided that the following conditions
7	* are met:	7	* are met:
Line 29...	Line 29...
29	/** @addtogroup net	29	/** @addtogroup net
30	* @{	30	* @{
31	*/	31	*/
32		32
33	/** @file	33	/** @file
34	* A character string with measured length header file.	34	* Character string with measured length.
35	* This structure has been designed for serialization of character strings between modules.	35	* The structure has been designed for serialization of character strings between modules.
36	*/	36	*/
37		37
38	#ifndef __MEASURED_STRINGS_H__	38	#ifndef __MEASURED_STRINGS_H__
39	#define __MEASURED_STRINGS_H__	39	#define __MEASURED_STRINGS_H__
40		40
41	/** A type definition of a character string with measured length.	41	/** Type definition of the character string with measured length.
42	* @see measured_string	42	* @see measured_string
43	*/	43	*/
44	typedef struct measured_string measured_string_t;	44	typedef struct measured_string measured_string_t;
45		45
46	/** A type definition of a character string with measured length pointer.	46	/** Type definition of the character string with measured length pointer.
47	* @see measured_string	47	* @see measured_string
48	*/	48	*/
49	typedef measured_string_t * measured_string_ref;	49	typedef measured_string_t * measured_string_ref;
50		50
51	/** A character string with measured length.	51	/** Character string with measured length.
52	* This structure has been designed for serialization of character strings between modules.	52	* This structure has been designed for serialization of character strings between modules.
53	*/	53	*/
54	struct measured_string{	54	struct measured_string{
55		-
56	/** The character string data.	55	/** Character string data.
57	*/	56	*/
58	char * value;	57	char * value;
59		-
60	/** The character string length.	58	/** Character string length.
61	*/	59	*/
62	size_t length;	60	size_t length;
63	};	61	};
64		62
65	/** Creates a new measured string bundled with a copy of the given string itself as one memory block.	63	/** Creates a new measured string bundled with a copy of the given string itself as one memory block.
66	* If the measured string is being freed, whole memory block is freed.	64	* If the measured string is being freed, whole memory block is freed.
67	* The measured string should be used only as a constant.	65	* The measured string should be used only as a constant.
68	* @param string The initial character string to be stored. Input parameter.	66	* @param string The initial character string to be stored. Input parameter.
69	* @param length The length of the given string without the terminating zero ('/0') character. If the length is zero (0), the actual length is computed. The given length is used and appended with the terminating zero ('\0') character otherwise. Input parameter.	67	* @param length The length of the given string without the terminating zero ('/0') character. If the length is zero (0), the actual length is computed. The given length is used and appended with the terminating zero ('\\0') character otherwise. Input parameter.
70	* @returns The new bundled charecter string with measured length.	68	* @returns The new bundled character string with measured length.
71	* @returns NULL if there is no memory left.	69	* @returns NULL if there is not enough memory left.
72	*/	70	*/
73	measured_string_ref measured_string_create_bulk( const char * string, size_t length );	71	measured_string_ref measured_string_create_bulk( const char * string, size_t length );
74		72
75	/** Receives a measured strings array from a calling module.	73	/** Receives a measured strings array from a calling module.
76	* Creates the array and the data memory blocks.	74	* Creates the array and the data memory blocks.
Line 81...	Line 79...
81	* @returns EOK on success.	79	* @returns EOK on success.
82	* @returns EINVAL if the strings or data parameter is NULL.	80	* @returns EINVAL if the strings or data parameter is NULL.
83	* @returns EINVAL if the count parameter is zero (0).	81	* @returns EINVAL if the count parameter is zero (0).
84	* @returns EINVAL if the sent array differs in size.	82	* @returns EINVAL if the sent array differs in size.
85	* @returns EINVAL if there is inconsistency in sent measured strings' lengths (should not occur).	83	* @returns EINVAL if there is inconsistency in sent measured strings' lengths (should not occur).
86	* @returns ENOMEM if there is no memory left.	84	* @returns ENOMEM if there is not enough memory left.
87	* @returns Other error codes as defined for the ipc_data_write_finalize() function.	85	* @returns Other error codes as defined for the ipc_data_write_finalize() function.
88	*/	86	*/
89	int measured_strings_receive( measured_string_ref * strings, char ** data, size_t count );	87	int measured_strings_receive( measured_string_ref * strings, char ** data, size_t count );
90		88
91	/** Replies the given measured strings array to a calling module.	89	/** Replies the given measured strings array to a calling module.
Line 110...	Line 108...
110	* @param count The size of the measured strings array. Input parameter.	108	* @param count The size of the measured strings array. Input parameter.
111	* @returns EOK on success.	109	* @returns EOK on success.
112	* @returns EINVAL if the strings or data parameter is NULL.	110	* @returns EINVAL if the strings or data parameter is NULL.
113	* @returns EINVAL if the phone or count parameter is not positive (<=0).	111	* @returns EINVAL if the phone or count parameter is not positive (<=0).
114	* @returns EINVAL if the sent array differs in size.	112	* @returns EINVAL if the sent array differs in size.
115	* @returns ENOMEM if there is no memory left.	113	* @returns ENOMEM if there is not enough memory left.
116	* @returns Other error codes as defined for the ipc_data_read_start() function.	114	* @returns Other error codes as defined for the ipc_data_read_start() function.
117	*/	115	*/
118	int measured_strings_return( int phone, measured_string_ref * strings, char ** data, size_t count );	116	int measured_strings_return( int phone, measured_string_ref * strings, char ** data, size_t count );
119		117
120	/** Sends the given measured strings array to another module.	118	/** Sends the given measured strings array to another module.

Subversion Repositories HelenOS

(root)/branches/network/uspace/srv/net/structures/measured_strings.h @ 3886 – Rev 3886 → 3912