Compare commits

...

1 Commits

Author SHA1 Message Date
Kai Huuhko 6404b05066 Add Python bindings for eet 2014-05-29 20:17:14 +03:00
18 changed files with 4075 additions and 0 deletions

6
doc/eet/cipher.rst Normal file
View File

@ -0,0 +1,6 @@
.. currentmodule:: efl.eet
.. _Eet_Cipher_Group:
Cipher, Identity and Protection Mechanisms
==========================================

10
doc/eet/data.rst Normal file
View File

@ -0,0 +1,10 @@
.. currentmodule:: efl.eet
.. _Eet_Data_Group:
Eet Data Serialization
=======================
.. autoclass:: EetDataDescriptor
.. autoclass:: EetDataDescriptorClass

17
doc/eet/eet.rst Normal file
View File

@ -0,0 +1,17 @@
:mod:`efl.eet` Module
=======================
.. automodule:: efl.eet
.. autofunction:: init
.. autofunction:: shutdown
.. autofunction:: clearcache
.. autoexception:: EetError
.. toctree::
file
cipher

21
doc/eet/file.rst Normal file
View File

@ -0,0 +1,21 @@
.. currentmodule:: efl.eet
.. _Eet_File_Group:
Eet File Main Functions
=======================
:class:`efl.eet.EetDictionary` Class
------------------------------------
.. autoclass:: EetDictionary
:class:`efl.eet.EetEntry` Class
--------------------------------
.. autoclass:: EetEntry
:class:`efl.eet.EetFile` Class
-------------------------------
.. autoclass:: EetFile

View File

@ -42,6 +42,11 @@ EO
.. toctree:: eo/eo.rst
Eet
---
.. toctree:: eet/eet
Ecore
-----

140
efl/eet/connection.pxi Normal file
View File

@ -0,0 +1,140 @@
"""
@typedef Eet_Connection
Opaque handle to track paquet for a specific connection.
"""
typedef struct _Eet_Connection Eet_Connection;
"""
@typedef Eet_Read_Cb
Called back when an :ref:`Eet_Data_Group` has been received completely and could be used.
"""
typedef Eina_Bool Eet_Read_Cb (const void *eet_data, size_t size, void *user_data);
"""
@typedef Eet_Write_Cb
Called back when a packet containing :ref:`Eet_Data_Group` data is ready to be send.
"""
typedef Eina_Bool Eet_Write_Cb (const void *data, size_t size, void *user_data);
"""
Instanciate a new connection to track.
:param eet_read_cb: Function to call when one Eet_Data packet has been fully assemble.
:param eet_write_cb: Function to call when one Eet_Data packet is ready to be send over the wire.
:param user_data: Pointer provided to both functions to be used as a context handler.
:return: NULL on failure, or a valid Eet_Connection handler.
For every connection to track you will need a separate Eet_Connection provider.
:since: 1.2.4
"""
EAPI Eet_Connection *
eet_connection_new(Eet_Read_Cb *eet_read_cb,
Eet_Write_Cb *eet_write_cb,
const void *user_data);
"""
Process a raw packet received over the link
:param conn: Connection handler to track.
:param data: Raw data packet.
:param size: The size of that packet.
:return: 0 on complete success, any other value indicate where in the stream it got wrong (It could be before that packet).
Every time you receive a packet related to your connection, you should pass
it to that function so that it could process and assemble packet has you
receive it. It will automatically call Eet_Read_Cb when one is fully received.
:since: 1.2.4
"""
EAPI int
eet_connection_received(Eet_Connection *conn,
const void *data,
size_t size);
"""
Tell if the Eet_Connection as received some partial data.
:param conn: Connection handler to request.
:return: EINA_TRUE if there is some data pending inside, EINA_FALSE otherwise.
Eet_Connection buffer data until the received data can be unserialized correctly. This
function let you know if there is some data inside that buffer waiting for more data to
be received before being processed.
:since: 1.7
"""
EAPI Eina_Bool eet_connection_empty(Eet_Connection *conn);
"""
Convert a complex structure and prepare it to be send.
:param conn: Connection handler to track.
:param edd: The data descriptor to use when encoding.
:param data_in: The pointer to the struct to encode into data.
:param cipher_key: The key to use as cipher.
:return: EINA_TRUE if the data where correctly send, EINA_FALSE if they don't.
This function serialize data_in with edd, assemble the packet and call
Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated
and will vanish just after the return of the callback.
:see: eet_data_descriptor_encode_cipher
:since: 1.2.4
"""
EAPI Eina_Bool
eet_connection_send(Eet_Connection *conn,
Eet_Data_Descriptor *edd,
const void *data_in,
const char *cipher_key);
"""
Convert a Eet_Node tree and prepare it to be send.
:param conn: Connection handler to track.
:param node: The data tree to use when encoding.
:param cipher_key: The key to use as cipher.
:return: EINA_TRUE if the data where correctly send, EINA_FALSE if they don't.
This function serialize node, assemble the packet and call
Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated
and will vanish just after the return of the callback.
:see: eet_data_node_encode_cipher
:since: 1.2.4
"""
EAPI Eina_Bool
eet_connection_node_send(Eet_Connection *conn,
Eet_Node *node,
const char *cipher_key);
"""
Close a connection and lost its track.
:param conn: Connection handler to close.
:param on_going: Signal if a partial packet wasn't completed.
:return: the user_data passed to both callback.
:since: 1.2.4
"""
EAPI void *
eet_connection_close(Eet_Connection *conn,
Eina_Bool *on_going);

653
efl/eet/data_descriptor.pxi Normal file
View File

@ -0,0 +1,653 @@
#define EET_T_UNKNOW 0 # Unknown data encoding type
#define EET_T_CHAR 1 # Data type: char
#define EET_T_SHORT 2 # Data type: short
#define EET_T_INT 3 # Data type: int
#define EET_T_LONG_LONG 4 # Data type: long long
#define EET_T_FLOAT 5 # Data type: float
#define EET_T_DOUBLE 6 # Data type: double
#define EET_T_UCHAR 7 # Data type: unsigned char
#define EET_T_USHORT 8 # Data type: unsigned short
#define EET_T_UINT 9 # Data type: unsigned int
#define EET_T_ULONG_LONG 10 # Data type: unsigned long long
#define EET_T_STRING 11 # Data type: char *
#define EET_T_INLINED_STRING 12 # Data type: char * (but compressed inside the resulting eet)
#define EET_T_NULL 13 # Data type: (void *) (only use it if you know why)
#define EET_T_F32P32 14 # Data type: fixed point 32.32
#define EET_T_F16P16 15 # Data type: fixed point 16.16
#define EET_T_F8P24 16 # Data type: fixed point 8.24
#define EET_T_VALUE 17 # Data type: pointer to Eina_Value :since: 1.8
#define EET_T_LAST 18 # Last data type
#define EET_G_UNKNOWN 100 # Unknown group data encoding type
#define EET_G_ARRAY 101 # Fixed size array group type
#define EET_G_VAR_ARRAY 102 # Variable size array group type
#define EET_G_LIST 103 # Linked list group type
#define EET_G_HASH 104 # Hash table group type
#define EET_G_UNION 105 # Union group type
#define EET_G_VARIANT 106 # Selectable subtype group
#define EET_G_UNKNOWN_NESTED 107 # Unknown nested group type. :since: 1.8
#define EET_G_LAST 108 # Last group type
#define EET_I_LIMIT 128 # Other type exist but are reserved for internal purpose.
cdef class EetDataDescriptor(object):
"""
Opaque handle that have information on a type members.
Descriptors are created using an #Eet_Data_Descriptor_Class, and they
describe the contents of the structure that will be serialized by Eet.
Not all members need be described by it, just those that should be handled
by Eet. This way it's possible to have one structure with both data to be
saved to a file, like application configuration, and runtime information
that would be meaningless to store, but is appropriate to keep together
during the program execution.
The members are added by means of
EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB(),
EET_DATA_DESCRIPTOR_ADD_LIST(), EET_DATA_DESCRIPTOR_ADD_HASH()
or eet_data_descriptor_element_add().
:see: eet_data_descriptor_stream_new()
:see: eet_data_descriptor_file_new()
:see: eet_data_descriptor_free()
"""
cdef Eet_Data_Descriptor *edd
def __init__(self, cls):
"""
This function creates a new data descriptor and returns a handle to the
new data descriptor. On creation it will be empty, containing no
contents describing anything other than the shell of the data structure.
:param eddc: The class from where to create the data descriptor.
:return: A handle to the new data descriptor.
You add structure members to the data descriptor using the macros
EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
adding to the description.
Once you have described all the members of a struct you want loaded or
saved, eet can load and save those members for you, encode them into
endian-independent serialised data chunks for transmission across a
network or more.
This function specially ignores str_direct_alloc and str_direct_free. It
is useful when the eet_data you are reading doesn't have a dictionary,
like network stream or IPC. It also mean that all string will be
allocated and duplicated in memory.
:since: 1.2.3
"""
self.edd = eet_data_descriptor_stream_new(cls.eddc)
def file_new(self, cls):
"""
This function creates a new data descriptor and returns a handle to the
new data descriptor. On creation it will be empty, containing no
contents describing anything other than the shell of the data structure.
:param eddc: The class from where to create the data descriptor.
:return: A handle to the new data descriptor.
You add structure members to the data descriptor using the macros
EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
adding to the description.
Once you have described all the members of a struct you want loaded or
saved, eet can load and save those members for you, encode them into
endian-independent serialised data chunks for transmission across a
a network or more.
This function uses str_direct_alloc and str_direct_free. It is useful
when the eet_data you are reading come from a file and have a
dictionary. This will reduce memory use and improve the possibility for
the OS to page this string out.
However, the load speed and memory saving comes with some drawbacks to
keep in mind. If you never modify the contents of the structures loaded
from the file, all you need to remember is that closing the eet file
will make the strings go away. On the other hand, should you need to
free a string, before doing so you have to verify that it's not part of
the eet dictionary. You can do this in the following way, assuming @p ef
is a valid Eet_File and @p str is a string loaded from said file.
@code
void eet_string_free(Eet_File *ef, const char *str)
{
Eet_Dictionary *dict = eet_dictionary_get(ef);
if (dict && eet_dictionary_string_check(dict, str))
{
// The file contains a dictionary and the given string is a part of
// of it, so we can't free it, just return.
return;
}
// We assume eina_stringshare was used on the descriptor
eina_stringshare_del(str);
}
@endcode
:since: 1.2.3
"""
self.edd = eet_data_descriptor_file_new(cls.eddc)
def free(self):
"""
This function frees a data descriptor when it is not needed anymore.
:param edd: The data descriptor to free.
This function takes a data descriptor handle as a parameter and frees all
data allocated for the data descriptor and the handle itself. After this
call the descriptor is no longer valid.
:since: 1.0.0
"""
eet_data_descriptor_free(self.edd)
property name:
"""
This function returns the name of a data descriptor.
:since: 1.8.0
"""
return _ctouni(eet_data_descriptor_name_get(self.edd)
def decode(self, data_in, size_in):
"""
Decode a data structure from an arbitrary location in memory.
:param edd: The data descriptor to use when decoding.
:param data_in: The pointer to the data to decode into a struct.
:param size_in: The size of the data pointed to in bytes.
:return: NULL on failure, or a valid decoded struct pointer on success.
This function will decode a data structure that has been encoded using
eet_data_descriptor_encode(), and return a data structure with all its
elements filled out, if successful, or NULL on failure.
The data to be decoded is stored at the memory pointed to by @p data_in,
and is described by the descriptor pointed to by @p edd. The data size is
passed in as the value to @p size_in, ande must be greater than 0 to
succeed.
This function is useful for decoding data structures delivered to the
application by means other than an eet file, such as an IPC or socket
connection, raw files, shared memory etc.
Please see eet_data_read() for more information.
@see eet_data_descriptor_decode_cipher()
:since: 1.0.0
"""
EAPI void *
eet_data_descriptor_decode(Eet_Data_Descriptor *edd,
const void *data_in,
int size_in);
def encode(self, data_in):
"""
Encode a dsata struct to memory and return that encoded data.
:param edd: The data descriptor to use when encoding.
:param data_in: The pointer to the struct to encode into data.
:param size_ret: pointer to the an int to be filled with the decoded size.
:return: NULL on failure, or a valid encoded data chunk on success.
This function takes a data structutre in memory and encodes it into a
serialised chunk of data that can be decoded again by
eet_data_descriptor_decode(). This is useful for being able to transmit
data structures across sockets, pipes, IPC or shared file mechanisms,
without having to worry about memory space, machine type, endianness etc.
The parameter @p edd must point to a valid data descriptor, and
@p data_in must point to the right data structure to encode. If not, the
encoding may fail.
On success a non NULL valid pointer is returned and what @p size_ret
points to is set to the size of this decoded data, in bytes. When the
encoded data is no longer needed, call free() on it. On failure NULL is
returned and what @p size_ret points to is set to 0.
Please see eet_data_write() for more information.
@see eet_data_descriptor_encode_cipher()
:since: 1.0.0
"""
EAPI void *
eet_data_descriptor_encode(Eet_Data_Descriptor *edd,
const void *data_in,
int *size_ret);
def decode_cipher(self, data_in, cipher_key, size_in):
"""
Decode a data structure from an arbitrary location in memory
using a cipher.
:param edd: The data descriptor to use when decoding.
:param data_in: The pointer to the data to decode into a struct.
:param cipher_key: The key to use as cipher.
:param size_in: The size of the data pointed to in bytes.
:return: NULL on failure, or a valid decoded struct pointer on success.
This function will decode a data structure that has been encoded using
eet_data_descriptor_encode(), and return a data structure with all its
elements filled out, if successful, or NULL on failure.
The data to be decoded is stored at the memory pointed to by @p data_in,
and is described by the descriptor pointed to by @p edd. The data size is
passed in as the value to @p size_in, ande must be greater than 0 to
succeed.
This function is useful for decoding data structures delivered to the
application by means other than an eet file, such as an IPC or socket
connection, raw files, shared memory etc.
Please see eet_data_read() for more information.
@see eet_data_descriptor_decode()
:since: 1.0.0
"""
EAPI void *
eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd,
const void *data_in,
const char *cipher_key,
int size_in);
def encode_cipher(self, data_in, cipher_key):
"""
Encode a data struct to memory and return that encoded data
using a cipher.
:param edd: The data descriptor to use when encoding.
:param data_in: The pointer to the struct to encode into data.
:param cipher_key: The key to use as cipher.
:param size_ret: pointer to the an int to be filled with the decoded size.
:return: NULL on failure, or a valid encoded data chunk on success.
This function takes a data structutre in memory and encodes it into a
serialised chunk of data that can be decoded again by
eet_data_descriptor_decode(). This is useful for being able to transmit
data structures across sockets, pipes, IPC or shared file mechanisms,
without having to worry about memory space, machine type, endianess etc.
The parameter @p edd must point to a valid data descriptor, and
@p data_in must point to the right data structure to encode. If not, the
encoding may fail.
On success a non NULL valid pointer is returned and what @p size_ret
points to is set to the size of this decoded data, in bytes. When the
encoded data is no longer needed, call free() on it. On failure NULL is
returned and what @p size_ret points to is set to 0.
Please see eet_data_write() for more information.
@see eet_data_descriptor_encode()
:since: 1.0.0
"""
EAPI void *
eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd,
const void *data_in,
const char *cipher_key,
int *size_ret);
def add_basic(self, struct_type, name, member, type):
"""
Add a basic data element to a data descriptor.
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
:param type: The type of the member to encode.
This macro is a convenience macro provided to add a member to
the data descriptor @p edd. The type of the structure is
provided as the @p struct_type parameter (for example: struct
my_struct). The @p name parameter defines a string that will be
used to uniquely name that member of the struct (it is suggested
to use the struct member itself). The @p member parameter is
the actual struct member itself (for example: values), and @p type is the
basic data type of the member which must be one of: EET_T_CHAR, EET_T_SHORT,
EET_T_INT, EET_T_LONG_LONG, EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR,
EET_T_USHORT, EET_T_UINT, EET_T_ULONG_LONG or EET_T_STRING.
:since: 1.0.0
"""
EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type)
def add_sub(self, struct_type, name, member, subtype):
"""
Add a sub-element type to a data descriptor
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
:param subtype: The type of sub-type struct to add.
This macro lets you easily add a sub-type (a struct that's pointed to
by this one). All the parameters are the same as for
EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the exception.
This must be the data descriptor of the struct that is pointed to by
this element.
:since: 1.0.0
"""
EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype)
def add_sub_nested(self, struct_type, name, member, subtype):
"""
Add a nested sub-element type to a data descriptor
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
:param subtype: The type of sub-type struct to add.
This macro lets you easily add a sub-type: a struct that is nested into
this one. If your data is pointed by this element instead of being nested,
you should use EET_DATA_DESCRIPTOR_ADD_SUB().
All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_SUB().
:since: 1.8.0
"""
EET_DATA_DESCRIPTOR_ADD_SUB_NESTED(edd, struct_type, name, member, subtype)
def add_list(self, struct_type, name, member, subtype):
"""
Add a linked list type to a data descriptor
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
:param subtype: The type of linked list member to add.
This macro lets you easily add a linked list of other data types. All the
parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
@p subtype being the exception. This must be the data descriptor of the
element that is in each member of the linked list to be stored.
:since: 1.0.0
"""
EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype)
def add_list_string(self, struct_type, name, member):
"""
Add a linked list of string to a data descriptor
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
This macro lets you easily add a linked list of char *. All the
parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
:since: 1.5.0
"""
EET_DATA_DESCRIPTOR_ADD_LIST_STRING(edd, struct_type, name, member)
def add_hash(self, struct_type, name, member, subtype):
"""
Add a hash type to a data descriptor
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
:param subtype: The type of hash member to add.
This macro lets you easily add a hash of other data types. All the
parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
@p subtype being the exception. This must be the data descriptor of the
element that is in each member of the hash to be stored.
The hash keys must be strings.
:since: 1.0.0
"""
EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtype)
def add_hash_string(self, struct_type, name, member):
"""
Add a hash of string to a data descriptor
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
This macro lets you easily add a hash of string elements. All the
parameters are the same as for EET_DATA_DESCRIPTOR_ADD_HASH().
:since: 1.3.4
"""
EET_DATA_DESCRIPTOR_ADD_HASH_STRING(edd, struct_type, name, member)
def add_basic_array(self, struct_type, name, member, type):
"""
Add an array of basic data elements to a data descriptor.
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
:param type: The type of the member to encode.
This macro lets you easily add a fixed size array of basic data
types. All the parameters are the same as for
EET_DATA_DESCRIPTOR_ADD_BASIC().
The array must be defined with a fixed size in the declaration of the
struct containing it.
:since: 1.5.0
"""
EET_DATA_DESCRIPTOR_ADD_BASIC_ARRAY(edd, struct_type, name, member, type)
def add_basic_var_array(self, struct_type, name, member, type):
"""
Add a variable array of basic data elements to a data descriptor.
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
:param type: The type of the member to encode.
This macro lets you easily add a variable size array of basic data
types. All the parameters are the same as for
EET_DATA_DESCRIPTOR_ADD_BASIC(). This assumes you have
a struct member (of type EET_T_INT) called member_count (note the
_count appended to the member) that holds the number of items in
the array. This array will be allocated separately to the struct it
is in.
:since: 1.6.0
"""
EET_DATA_DESCRIPTOR_ADD_BASIC_VAR_ARRAY(edd, struct_type, name, member, type)
def add_array(self, struct_type, name, member, subtype):
"""
Add a fixed size array type to a data descriptor
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
:param subtype: The type of hash member to add.
This macro lets you easily add a fixed size array of other data
types. All the parameters are the same as for
EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
exception. This must be the data descriptor of the element that
is in each member of the array to be stored.
The array must be defined with a fixed size in the declaration of the
struct containing it.
:since: 1.0.2
"""
EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subtype)
def add_var_array(self, struct_type, name, member, subtype):
"""
Add a variable size array type to a data descriptor
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
:param subtype: The type of hash member to add.
This macro lets you easily add a variable size array of other data
types. All the parameters are the same as for
EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
exception. This must be the data descriptor of the element that
is in each member of the array to be stored. This assumes you have
a struct member (of type EET_T_INT) called member_count (note the
_count appended to the member) that holds the number of items in
the array. This array will be allocated separately to the struct it
is in.
:since: 1.0.2
"""
EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, subtype)
def add_var_array_string(self, struct_type, name, member):
"""
Add a variable size array type to a data descriptor
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
This macro lets you easily add a variable size array of strings. All
the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
:since: 1.4.0
"""
EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING(edd, struct_type, name, member)
def add_union(self, struct_type, name, member, type_member, unified_type):
"""
Add an union type to a data descriptor
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
:param type_member: The member that give hints on what is in the union.
:param unified_type: Describe all possible type the union could handle.
This macro lets you easily add an union with a member that specify what is inside.
The @p unified_type is an Eet_Data_Descriptor, but only the entry that match the name
returned by type_get will be used for each serialized data. The type_get and type_set
callback of unified_type should be defined.
:since: 1.2.4
:see: Eet_Data_Descriptor_Class
"""
EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member, type_member, unified_type)
def add_variant(self, struct_type, name, member, type_member, unified_type):
"""
Add a automatically selectable type to a data descriptor
:param edd: The data descriptor to add the type to.
:param struct_type: The type of the struct.
:param name: The string name to use to encode/decode this member
(must be a constant global and never change).
:param member: The struct member itself to be encoded.
:param type_member: The member that give hints on what is in the union.
:param unified_type: Describe all possible type the union could handle.
This macro lets you easily define what the content of @p member points to depending of
the content of @p type_member. The type_get and type_set callback of unified_type should
be defined. If the the type is not know at the time of restoring it, eet will still call
type_set of @p unified_type but the pointer will be set to a serialized binary representation
of what eet know. This make it possible, to save this pointer again by just returning the string
given previously and telling it by setting unknow to EINA_TRUE.
:since: 1.2.4
:see: Eet_Data_Descriptor_Class
"""
EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member, type_member, unified_type)
def add_mapping(self, name, subtype):
"""
Add a mapping to a data descriptor that will be used by union, variant or inherited type
:param unified_type: The data descriptor to add the mapping to.
:param name: The string name to get/set type.
:param subtype: The matching data descriptor.
:since: 1.2.4
:see: Eet_Data_Descriptor_Class
"""
EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype)
def add_mapping_basic(self, name, basic_type):
"""
Add a mapping of a basic type to a data descriptor that will be used by a union type.
:param unified_type: The data descriptor to add the mapping to.
:param name: The string name to get/set type.
:param basic_type: The matching basic type.
:since: 1.8
:see: Eet_Data_Descriptor_Class
"""
EET_DATA_DESCRIPTOR_ADD_MAPPING_BASIC(unified_type, name, basic_type)

View File

@ -0,0 +1,176 @@
"""
@def EET_DATA_DESCRIPTOR_CLASS_VERSION
The version of #Eet_Data_Descriptor_Class at the time of the
distribution of the sources. One should define this to its
version member so it is compatible with abi changes, or at least
will not crash with them.
"""
#define EET_DATA_DESCRIPTOR_CLASS_VERSION 4
"""
@typedef Eet_Data_Descriptor_Class
Instructs Eet about memory management for different needs under
serialization and parse process.
"""
typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class;
typedef int (*Eet_Descriptor_Hash_Foreach_Callback_Callback)(void *h, const char *k, void *dt, void *fdt);
typedef void * (*Eet_Descriptor_Mem_Alloc_Callback)(size_t size);
typedef void (*Eet_Descriptor_Mem_Free_Callback)(void *mem);
typedef char * (*Eet_Descriptor_Str_Alloc_Callback)(const char *str);
typedef void (*Eet_Descriptor_Str_Free_Callback)(const char *str);
typedef void * (*Eet_Descriptor_List_Next_Callback)(void *l);
typedef void * (*Eet_Descriptor_List_Append_Callback)(void *l, void *d);
typedef void * (*Eet_Descriptor_List_Data_Callback)(void *l);
typedef void * (*Eet_Descriptor_List_Free_Callback)(void *l);
typedef void (*Eet_Descriptor_Hash_Foreach_Callback)(void *h, Eet_Descriptor_Hash_Foreach_Callback_Callback func, void *fdt);
typedef void * (*Eet_Descriptor_Hash_Add_Callback)(void *h, const char *k, void *d);
typedef void (*Eet_Descriptor_Hash_Free_Callback)(void *h);
typedef char * (*Eet_Descriptor_Str_Direct_Alloc_Callback)(const char *str);
typedef void (*Eet_Descriptor_Str_Direct_Free_Callback)(const char *str);
typedef const char * (*Eet_Descriptor_Type_Get_Callback)(const void *data, Eina_Bool *unknow);
typedef Eina_Bool (*Eet_Descriptor_Type_Set_Callback)(const char *type, void *data, Eina_Bool unknow);
typedef void * (*Eet_Descriptor_Array_Alloc_Callback)(size_t size);
typedef void (*Eet_Descriptor_Array_Free_Callback)(void *mem);
"""
@struct _Eet_Data_Descriptor_Class
Instructs Eet about memory management for different needs under
serialization and parse process.
The list and hash methods match the Eina API, so for a more detailed
reference on them, look at the Eina_List and Eina_Hash documentation,
respectively.
For the most part these will be used with the standard Eina functions,
so using EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and
EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET() will set up everything
accordingly.
"""
struct _Eet_Data_Descriptor_Class
{
int version; # ABI version. Should always be set to #EET_DATA_DESCRIPTOR_CLASS_VERSION
const char *name; # Name of the user data type to be serialized
int size; # Size in bytes of the user data type to be serialized
struct
{
Eet_Descriptor_Mem_Alloc_Callback mem_alloc; # how to allocate memory (usually malloc())
Eet_Descriptor_Mem_Free_Callback mem_free; # how to free memory (usually free())
Eet_Descriptor_Str_Alloc_Callback str_alloc; # how to allocate a string
Eet_Descriptor_Str_Free_Callback str_free; # how to free a string
Eet_Descriptor_List_Next_Callback list_next; # how to iterate to the next element of a list. Receives and should return the list node.
Eet_Descriptor_List_Append_Callback list_append; # how to append data @p d to list which head node is @p l
Eet_Descriptor_List_Data_Callback list_data; # retrieves the data from node @p l
Eet_Descriptor_List_Free_Callback list_free; # free all the nodes from the list which head node is @p l
Eet_Descriptor_Hash_Foreach_Callback hash_foreach; # iterates over all elements in the hash @p h in no specific order
Eet_Descriptor_Hash_Add_Callback hash_add; # add a new data @p d with key @p k in hash @p h
Eet_Descriptor_Hash_Free_Callback hash_free; # free all entries from the hash @p h
Eet_Descriptor_Str_Direct_Alloc_Callback str_direct_alloc; # how to allocate a string directly from file backed/mmaped region pointed by @p str
Eet_Descriptor_Str_Direct_Free_Callback str_direct_free; # how to free a string returned by str_direct_alloc
Eet_Descriptor_Type_Get_Callback type_get; # get the type, as used in the union or variant mapping, that should be used to store the given data into the eet file.
Eet_Descriptor_Type_Set_Callback type_set; # called when loading a mapped type with the given @p type used to describe the type in the descriptor
Eet_Descriptor_Array_Alloc_Callback array_alloc; # how to allocate memory for array (usually malloc())
Eet_Descriptor_Array_Free_Callback array_free; # how to free memory for array (usually free())
} func;
};
"""
This function is an helper that set all the parameters of an
Eet_Data_Descriptor_Class correctly when you use Eina data type
with a stream.
:param eddc: The Eet_Data_Descriptor_Class you want to set.
:param eddc_size: The size of the Eet_Data_Descriptor_Class at the compilation time.
:param name: The name of the structure described by this class.
:param size: The size of the structure described by this class.
:return: EINA_TRUE if the structure was correctly set (The only
reason that could make it fail is if you did give wrong
parameter).
@note Unless there's a very specific reason to use this function directly,
the EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET macro is recommended.
:since: 1.2.3
"""
EAPI Eina_Bool
eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
unsigned int eddc_size,
const char *name,
int size);
"""
This macro is an helper that set all the parameter of an
Eet_Data_Descriptor_Class correctly when you use Eina data type
with stream.
:param clas: The Eet_Data_Descriptor_Class you want to set.
:param type: The type of the structure described by this class.
:return: EINA_TRUE if the structure was correctly set (The only
reason that could make it fail is if you did give wrong
parameter).
:see: eet_data_descriptor_stream_new
:since: 1.2.3
"""
#define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type) \
(eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
"""
This function is an helper that set all the parameter of an
Eet_Data_Descriptor_Class correctly when you use Eina data type
with a file.
:param eddc: The Eet_Data_Descriptor_Class you want to set.
:param eddc_size: The size of the Eet_Data_Descriptor_Class at the compilation time.
:param name: The name of the structure described by this class.
:param size: The size of the structure described by this class.
:return: EINA_TRUE if the structure was correctly set (The only
reason that could make it fail is if you did give wrong
parameter).
@note Unless there's a very specific reason to use this function directly,
the EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET macro is recommended.
:since: 1.2.3
"""
EAPI Eina_Bool
eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
unsigned int eddc_size,
const char *name,
int size);
"""
This macro is an helper that set all the parameter of an
Eet_Data_Descriptor_Class correctly when you use Eina data type
with file.
:param clas: The Eet_Data_Descriptor_Class you want to set.
:param type: The type of the structure described by this class.
:return: EINA_TRUE if the structure was correctly set (The only
reason that could make it fail is if you did give wrong
parameter).
:see: eet_data_descriptor_file_new
:since: 1.2.3
"""
#define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(clas, type) \
(eet_eina_file_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))

622
efl/eet/data_utils.pxi Normal file
View File

@ -0,0 +1,622 @@
"""
Decode Image data header only to get information.
:param data: The encoded pixel data.
:param size: The size, in bytes, of the encoded pixel data.
:param w: A pointer to the unsigned int to hold the width in pixels.
:param h: A pointer to the unsigned int to hold the height in pixels.
:param alpha: A pointer to the int to hold the alpha flag.
:param compress: A pointer to the int to hold the compression amount.
:param quality: A pointer to the int to hold the quality amount.
:param lossy: A pointer to the int to hold the lossiness flag.
:return: 1 on success, 0 on failure.
This function works exactly like eet_data_image_header_read(), but instead
of reading from an Eet file, it takes the buffer of size @p size pointed
by @p data, which must be a valid Eet encoded image.
On success the function returns 1 indicating the header was read and
decoded properly, or 0 on failure.
@see eet_data_image_header_read()
@see eet_data_image_header_decode_cipher()
:since: 1.0.0
"""
EAPI int
eet_data_image_header_decode(const void *data,
int size,
unsigned int *w,
unsigned int *h,
int *alpha,
int *compress,
int *quality,
int *lossy);
"""
Decode Image data into pixel data.
:param data: The encoded pixel data.
:param size: The size, in bytes, of the encoded pixel data.
:param w: A pointer to the unsigned int to hold the width in pixels.
:param h: A pointer to the unsigned int to hold the height in pixels.
:param alpha: A pointer to the int to hold the alpha flag.
:param compress: A pointer to the int to hold the compression amount.
:param quality: A pointer to the int to hold the quality amount.
:param lossy: A pointer to the int to hold the lossiness flag.
:return: The image pixel data decoded
This function takes encoded pixel data and decodes it into raw RGBA
pixels on success.
It works exactly like eet_data_image_read(), but it takes the encoded
data in the @p data buffer of size @p size, instead of reading from a file.
All the others parameters are also the same.
On success the function returns a pointer to the image data decoded. The
calling application is responsible for calling free() on the image data
when it is done with it. On failure NULL is returned and the parameter
values may not contain any sensible data.
@see eet_data_image_read()
@see eet_data_image_decode_cipher()
:since: 1.0.0
"""
EAPI void *
eet_data_image_decode(const void *data,
int size,
unsigned int *w,
unsigned int *h,
int *alpha,
int *compress,
int *quality,
int *lossy);
"""
Decode Image data into pixel data and stores in the given buffer.
:param data: The encoded pixel data.
:param size: The size, in bytes, of the encoded pixel data.
:param src_x: The starting x coordinate from where to dump the stream.
:param src_y: The starting y coordinate from where to dump the stream.
:param d: A pointer to the pixel surface.
:param w: The expected width in pixels of the pixel surface to decode.
:param h: The expected height in pixels of the pixel surface to decode.
:param row_stride: The length of a pixels line in the destination surface.
:param alpha: A pointer to the int to hold the alpha flag.
:param compress: A pointer to the int to hold the compression amount.
:param quality: A pointer to the int to hold the quality amount.
:param lossy: A pointer to the int to hold the lossiness flag.
:return: 1 on success, 0 otherwise.
Like eet_data_image_read_to_surface(), but reading the given @p data buffer
instead of a file.
On success the function returns 1, and 0 on failure. On failure the
parameter values may not contain any sensible data.
@see eet_data_image_read_to_surface()
@see eet_data_image_decode_to_surface_cipher()
:since: 1.0.2
"""
EAPI int
eet_data_image_decode_to_surface(const void *data,
int size,
unsigned int src_x,
unsigned int src_y,
unsigned int *d,
unsigned int w,
unsigned int h,
unsigned int row_stride,
int *alpha,
int *compress,
int *quality,
int *lossy);
"""
Encode image data for storage or transmission.
:param data: A pointer to the image pixel data.
:param size_ret: A pointer to an int to hold the size of the returned data.
:param w: The width of the image in pixels.
:param h: The height of the image in pixels.
:param alpha: The alpha channel flag.
:param compress: The compression amount.
:param quality: The quality encoding amount.
:param lossy: The lossiness flag.
:return: The encoded image data.
This function stakes image pixel data and encodes it with compression and
possible loss of quality (as a trade off for size) for storage or
transmission to another system.
It works like eet_data_image_write(), but instead of writing the encoded
image into an Eet file, it allocates a new buffer of the size required and
returns the encoded data in it.
On success this function returns a pointer to the encoded data that you
can free with free() when no longer needed.
@see eet_data_image_write()
@see eet_data_image_read()
@see eet_data_image_encode_cipher()
:since: 1.0.0
"""
EAPI void *
eet_data_image_encode(const void *data,
int *size_ret,
unsigned int w,
unsigned int h,
int alpha,
int compress,
int quality,
int lossy);
"""
Decode Image data header only to get information using a cipher.
:param data: The encoded pixel data.
:param cipher_key: The key to use as cipher.
:param size: The size, in bytes, of the encoded pixel data.
:param w: A pointer to the unsigned int to hold the width in pixels.
:param h: A pointer to the unsigned int to hold the height in pixels.
:param alpha: A pointer to the int to hold the alpha flag.
:param compress: A pointer to the int to hold the compression amount.
:param quality: A pointer to the int to hold the quality amount.
:param lossy: A pointer to the int to hold the lossiness flag.
:return: 1 on success, 0 on failure.
This function takes encoded pixel data and decodes it into raw RGBA
pixels on success.
The other parameters of the image (width, height etc.) are placed into
the values pointed to (they must be supplied). The pixel data is a linear
array of pixels starting from the top-left of the image scanning row by
row from left to right. Each pixel is a 32bit value, with the high byte
being the alpha channel, the next being red, then green, and the low byte
being blue. The width and height are measured in pixels and will be
greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
that the alpha channel is not used. 1 denotes that it is significant.
Compress is filled with the compression value/amount the image was
stored with. The quality value is filled with the quality encoding of
the image file (0 - 100). The lossy flags is either 0 or 1 as to if
the image was encoded lossily or not.
On success the function returns 1 indicating the header was read and
decoded properly, or 0 on failure.
@see eet_data_image_header_decode()
:since: 1.0.0
"""
EAPI int
eet_data_image_header_decode_cipher(const void *data,
const char *cipher_key,
int size,
unsigned int *w,
unsigned int *h,
int *alpha,
int *compress,
int *quality,
int *lossy);
"""
Decode Image data into pixel data using a cipher.
:param data: The encoded pixel data.
:param cipher_key: The key to use as cipher.
:param size: The size, in bytes, of the encoded pixel data.
:param w: A pointer to the unsigned int to hold the width in pixels.
:param h: A pointer to the unsigned int to hold the height in pixels.
:param alpha: A pointer to the int to hold the alpha flag.
:param compress: A pointer to the int to hold the compression amount.
:param quality: A pointer to the int to hold the quality amount.
:param lossy: A pointer to the int to hold the lossiness flag.
:return: The image pixel data decoded
This function takes encoded pixel data and decodes it into raw RGBA
pixels on success.
The other parameters of the image (width, height etc.) are placed into
the values pointed to (they must be supplied). The pixel data is a linear
array of pixels starting from the top-left of the image scanning row by
row from left to right. Each pixel is a 32bit value, with the high byte
being the alpha channel, the next being red, then green, and the low byte
being blue. The width and height are measured in pixels and will be
greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
that the alpha channel is not used. 1 denotes that it is significant.
Compress is filled with the compression value/amount the image was
stored with. The quality value is filled with the quality encoding of
the image file (0 - 100). The lossy flags is either 0 or 1 as to if
the image was encoded lossily or not.
On success the function returns a pointer to the image data decoded. The
calling application is responsible for calling free() on the image data
when it is done with it. On failure NULL is returned and the parameter
values may not contain any sensible data.
@see eet_data_image_decode()
:since: 1.0.0
"""
EAPI void *
eet_data_image_decode_cipher(const void *data,
const char *cipher_key,
int size,
unsigned int *w,
unsigned int *h,
int *alpha,
int *compress,
int *quality,
int *lossy);
"""
Decode Image data into pixel data using a cipher.
:param data: The encoded pixel data.
:param cipher_key: The key to use as cipher.
:param size: The size, in bytes, of the encoded pixel data.
:param src_x: The starting x coordinate from where to dump the stream.
:param src_y: The starting y coordinate from where to dump the stream.
:param d: A pointer to the pixel surface.
:param w: The expected width in pixels of the pixel surface to decode.
:param h: The expected height in pixels of the pixel surface to decode.
:param row_stride: The length of a pixels line in the destination surface.
:param alpha: A pointer to the int to hold the alpha flag.
:param compress: A pointer to the int to hold the compression amount.
:param quality: A pointer to the int to hold the quality amount.
:param lossy: A pointer to the int to hold the lossiness flag.
:return: 1 on success, 0 otherwise.
This function takes encoded pixel data and decodes it into raw RGBA
pixels on success.
The other parameters of the image (alpha, compress etc.) are placed into
the values pointed to (they must be supplied). The pixel data is a linear
array of pixels starting from the top-left of the image scanning row by
row from left to right. Each pixel is a 32bit value, with the high byte
being the alpha channel, the next being red, then green, and the low byte
being blue. The width and height are measured in pixels and will be
greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
that the alpha channel is not used. 1 denotes that it is significant.
Compress is filled with the compression value/amount the image was
stored with. The quality value is filled with the quality encoding of
the image file (0 - 100). The lossy flags is either 0 or 1 as to if
the image was encoded lossily or not.
On success the function returns 1, and 0 on failure. On failure the
parameter values may not contain any sensible data.
@see eet_data_image_decode_to_surface()
:since: 1.0.2
"""
EAPI int
eet_data_image_decode_to_surface_cipher(const void *data,
const char *cipher_key,
int size,
unsigned int src_x,
unsigned int src_y,
unsigned int *d,
unsigned int w,
unsigned int h,
unsigned int row_stride,
int *alpha,
int *compress,
int *quality,
int *lossy);
"""
Encode image data for storage or transmission using a cipher.
:param data: A pointer to the image pixel data.
:param cipher_key: The key to use as cipher.
:param size_ret: A pointer to an int to hold the size of the returned data.
:param w: The width of the image in pixels.
:param h: The height of the image in pixels.
:param alpha: The alpha channel flag.
:param compress: The compression amount.
:param quality: The quality encoding amount.
:param lossy: The lossiness flag.
:return: The encoded image data.
This function stakes image pixel data and encodes it with compression and
possible loss of quality (as a trade off for size) for storage or
transmission to another system.
The data expected is the same format as returned by eet_data_image_read.
If this is not the case weird things may happen. Width and height must
be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
the alpha values are not useful and 1 meaning they are). Compress can
be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
This is only used if the image is not lossily encoded. Quality is used on
lossy compression and should be a value from 0 to 100. The lossy flag
can be 0 or 1. 0 means encode losslessly and 1 means to encode with
image quality loss (but then have a much smaller encoding).
On success this function returns a pointer to the encoded data that you
can free with free() when no longer needed.
@see eet_data_image_encode()
:since: 1.0.0
"""
EAPI void *
eet_data_image_encode_cipher(const void *data,
const char *cipher_key,
unsigned int w,
unsigned int h,