Tizen Native API
Functions | Typedefs
Ecore File Descriptor Handling
Ecore Main Loop

This group discusses functions that deal with file descriptor handlers.

File descriptor handlers facilitate reading, writing, and checking for errors without blocking the program or doing expensive pooling. This can be used to monitor a socket, pipe, or some other stream for which an FD can be present.

File descriptor handlers can't be used to monitor file creation, modification, or deletion,

One common FD to be monitored is the standard input(stdin), monitoring it for reading requires a single call: 

 static Eina_Bool
 _my_cb_func(void *data, Ecore_Fd_Handler *handler)
 {
    char c;
    scanf("%c", &c); //Guaranteed not to block
    ... do stuff with c ...
 }
 ecore_main_fd_handler_add(STDIN_FILENO, ECORE_FD_READ, _my_cb_func, NULL, NULL, NULL);

When using a socket, pipe, or some other stream it's important to remember that errors may occur and we must monitor not only for reading/writing, but also for errors using the ECORE_FD_ERROR flag.

Functions

Ecore_Fd_Handler * ecore_main_fd_handler_add (int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data)
 Adds a callback for activity on the given file descriptor.
Ecore_Fd_Handler * ecore_main_fd_handler_file_add (int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data)
 Adds a callback for activity on the given file descriptor.
void ecore_main_fd_handler_prepare_callback_set (Ecore_Fd_Handler *fd_handler, Ecore_Fd_Prep_Cb func, const void *data)
 Sets the prepare callback with data for a given Ecore_Fd_Handler.
void * ecore_main_fd_handler_del (Ecore_Fd_Handler *fd_handler)
 Marks an FD handler for deletion.
int ecore_main_fd_handler_fd_get (Ecore_Fd_Handler *fd_handler)
 Retrieves the file descriptor that the given handler is handling.
Eina_Bool ecore_main_fd_handler_active_get (Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags)
 Gets which flags are active on an FD handler.
void ecore_main_fd_handler_active_set (Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags)
 Sets what active streams the given FD handler should be monitoring.

Typedefs

typedef struct _Ecore_Fd_Handler Ecore_Fd_Handler
 typedef to struct _Ecore_Fd_Handler
typedef enum
_Ecore_Fd_Handler_Flags 		Ecore_Fd_Handler_Flags
 typedef to enum _Ecore_Fd_Handler_Flags
typedef Eina_Bool(* Ecore_Fd_Cb )(void *data, Ecore_Fd_Handler *fd_handler)
 The boolean type for a callback used by an Ecore_Fd_Handler.
typedef void(* Ecore_Fd_Prep_Cb )(void *data, Ecore_Fd_Handler *fd_handler)
 Called to be used by an Ecore_Fd_Handler.

Typedef Documentation

typedef struct _Ecore_Fd_Handler Ecore_Fd_Handler

typedef to struct _Ecore_Fd_Handler

A handle for FD handlers

Enumeration Type Documentation

enum _Ecore_Fd_Handler_Flags

Enumeration that defines the handler flags to monitor the file descriptor for: reading, writing, or error.

Enumerator:
ECORE_FD_READ 

FD Read mask

ECORE_FD_WRITE 

FD Write mask

ECORE_FD_ERROR 

FD Error mask

Function Documentation

Eina_Bool ecore_main_fd_handler_active_get ( Ecore_Fd_Handler *  fd_handler,
Ecore_Fd_Handler_Flags  flags 
)

Gets which flags are active on an FD handler.

Since :
2.3.1
Parameters:
[in]fd_handlerThe given fd handler
[in]flagsThe flags, ECORE_FD_READ, ECORE_FD_WRITE, or ECORE_FD_ERROR to query
Returns:
EINA_TRUE if any of the given flags are active, otherwise EINA_FALSE
void ecore_main_fd_handler_active_set ( Ecore_Fd_Handler *  fd_handler,
Ecore_Fd_Handler_Flags  flags 
)

Sets what active streams the given FD handler should be monitoring.

Since :
2.3.1
Parameters:
[in]fd_handlerThe given fd handler
[in]flagsThe flags to be watching
Ecore_Fd_Handler* ecore_main_fd_handler_add ( int  fd,
Ecore_Fd_Handler_Flags  flags,
Ecore_Fd_Cb  func,
const void *  data,
Ecore_Fd_Cb  buf_func,
const void *  buf_data 
)

Adds a callback for activity on the given file descriptor.

Since :
2.3.1
Remarks:
func is called during the execution of The Ecore Main Loop when the file descriptor is available for reading, writing, or there has been an error(depending on the given flags).
When func returns ECORE_CALLBACK_CANCEL, it indicates that the handler should be marked for deletion (identical to calling ecore_main_fd_handler_del).
buf_func is meant for internal use only and should be avoided.
The return value of buf_func has a different meaning, when it returns ECORE_CALLBACK_CANCEL, it indicates that func shouldn't be called, and when it returns ECORE_CALLBACK_RENEW it indicates func should be called. The return value of buf_func does not cause the FD handler to get deleted.
buf_func is called during event loop handling to check if data that has been read from the file descriptor is in a buffer and is available to read. Some systems, notably xlib, handle their own buffering, and would otherwise not work with select(). These systems should use a buf_func. This is the most annoying hack, only ecore_x uses it, so refer to that for an example.
This function should not be used for monitoring "normal" files, like text files.
Parameters:
[in]fdThe file descriptor to watch
[in]flagsThe flags to monitor it, for reading use ECORE_FD_READ, for writing use ECORE_FD_WRITE, and for error use ECORE_FD_ERROR
Values by |(ored).
[in]funcThe callback function
[in]dataThe data to pass to the callback
[in]buf_funcThe function to call to check if any data has been buffered and already read from the fd
May be NULL.
[in]buf_dataThe data to pass to the buf_func function
Returns:
An fd handler handle on success, otherwise NULL on failure
void* ecore_main_fd_handler_del ( Ecore_Fd_Handler *  fd_handler)

Marks an FD handler for deletion.

Since :
2.3.1

This function marks an fd handler to be deleted during an iteration of the main loop. It does NOT close the associated fd.

Remarks:
If the underlying fd is already closed ecore may complain if the main loop is using epoll internally, and also in some rare cases this may cause crashes and instability. Remember to delete your fd handlers before the fds they listen to are closed.
Parameters:
[in]fd_handlerThe fd handler
Returns:
The data pointer set using ecore_main_fd_handler_add, for fd_handler on success, otherwise NULL on failure
int ecore_main_fd_handler_fd_get ( Ecore_Fd_Handler *  fd_handler)

Retrieves the file descriptor that the given handler is handling.

Since :
2.3.1
Parameters:
[in]fd_handlerThe given fd handler
Returns:
The file descriptor that the handler is watching
Ecore_Fd_Handler* ecore_main_fd_handler_file_add ( int  fd,
Ecore_Fd_Handler_Flags  flags,
Ecore_Fd_Cb  func,
const void *  data,
Ecore_Fd_Cb  buf_func,
const void *  buf_data 
)

Adds a callback for activity on the given file descriptor.

Since (EFL) :
1.7
Since :
2.3.1
Remarks:
This function is identical to ecore_main_fd_handler_add, except that it supports regular files.
This function should ONLY be called with ECORE_FD_ERROR, otherwise it calls the fd handler constantly.
Do not use this function unless you know what you are doing.
Parameters:
[in]fdThe file descriptor to watch
[in]flagsThe flags to monitor it, for reading use ECORE_FD_READ, for writing use ECORE_FD_WRITE, and for error use ECORE_FD_ERROR
Values by |(ored).
[in]funcThe callback function
[in]dataThe data to pass to the callback
[in]buf_funcThe function to call to check if any data has been buffered and already read from the fd
May be NULL.
[in]buf_dataThe data to pass to the buf_func function.
Returns:
An fd handler handle on success, otherwise NULL on failure
void ecore_main_fd_handler_prepare_callback_set ( Ecore_Fd_Handler *  fd_handler,
Ecore_Fd_Prep_Cb  func,
const void *  data 
)

Sets the prepare callback with data for a given Ecore_Fd_Handler.

Since :
2.3.1
Remarks:
This function is called prior to any fd handler's callback function (even the other fd handlers), before entering the main loop select function.
Once a prepare callback is set for an fd handler, it cannot be changed. You need to delete the fd handler and create a new one, to set another callback.
You probably don't need this function. It is only necessary for very uncommon cases that need special behavior.
Parameters:
[in]fd_handlerThe fd handler
[in]funcThe prep function
[in]dataThe data to pass to the prep function