Synopsis

struct              NtdDevice;
struct              NtdDeviceClass;
enum                NtdDumpMode;
gboolean            ntd_device_clear_error              (NtdDevice *device);
void                ntd_device_close                    (NtdDevice *device);
void                ntd_device_flush                    (NtdDevice *device,
                                                         gboolean input,
                                                         gboolean output);
gint8               ntd_device_get_boc                  (NtdDevice *device);
NtdDumpMode         ntd_device_get_dump_mode            (NtdDevice *device);
gint8               ntd_device_get_eoc                  (NtdDevice *device);
GError *            ntd_device_get_error                (NtdDevice *device);
const gchar *       ntd_device_get_file                 (NtdDevice *device);
gboolean            ntd_device_in_error                 (NtdDevice *device);
gboolean            ntd_device_is_opened                (NtdDevice *device);
void                ntd_device_open                     (NtdDevice *device);
gboolean            ntd_device_printf                   (NtdDevice *device,
                                                         const gchar *format,
                                                         ...);
gpointer            ntd_device_read                     (NtdDevice *device,
                                                         gsize nbytes);
gpointer            ntd_device_read_until               (NtdDevice *device,
                                                         gchar eol);
void                ntd_device_set_boc                  (NtdDevice *device,
                                                         gint8 boc);
void                ntd_device_set_dump_mode            (NtdDevice *device,
                                                         NtdDumpMode dump_mode);
void                ntd_device_set_eoc                  (NtdDevice *device,
                                                         gint8 eoc);
void                ntd_device_set_error                (NtdDevice *device,
                                                         NtdSystemError error_code,
                                                         const gchar *format,
                                                         ...);
gboolean            ntd_device_set_error_from_system    (NtdDevice *device,
                                                         const gchar *format,
                                                         ...);
void                ntd_device_set_errorv               (NtdDevice *device,
                                                         NtdSystemError error_code,
                                                         const gchar *format,
                                                         va_list args);
void                ntd_device_set_file                 (NtdDevice *device,
                                                         const gchar *file);
gboolean            ntd_device_vprintf                  (NtdDevice *device,
                                                         const gchar *format,
                                                         va_list var_args);
gboolean            ntd_device_write                    (NtdDevice *device,
                                                         gsize nbytes,
                                                         gconstpointer buffer);

Object Hierarchy

  GObject
   +----NtdDevice
         +----NtdNull
         +----NtdSerial

Properties

  "boc"                      gchar                 : Read / Write
  "dump-mode"                NtdDumpMode           : Read / Write
  "eoc"                      gchar                 : Read / Write
  "file"                     gchar*                : Read / Write

Signals

  "close"                                          : No Recursion
  "error-set"                                      : No Recursion
  "flush"                                          : No Recursion
  "open"                                           : No Recursion
  "read"                                           : No Recursion
  "write"                                          : No Recursion

Description

Details

struct NtdDevice

struct NtdDevice;

struct NtdDeviceClass

struct NtdDeviceClass {
};

enum NtdDumpMode

typedef enum {
    NTD_DUMP_MODE_NONE,
    NTD_DUMP_MODE_RAW,
    NTD_DUMP_MODE_RAW_READ,
    NTD_DUMP_MODE_RAW_WRITE,
    NTD_DUMP_MODE_FRIENDLY,
    NTD_DUMP_MODE_FRIENDLY_READ,
    NTD_DUMP_MODE_FRIENDLY_WRITE
} NtdDumpMode;

ntd_device_clear_error ()

gboolean            ntd_device_clear_error              (NtdDevice *device);

Resets the device internal error.

device :

an NtdDevice based instance

Returns :

TRUE if there was an internal error, FALSE otherwise.

ntd_device_close ()

void                ntd_device_close                    (NtdDevice *device);

Terminates the communication on device.

The device is automatically closed whenever the object is destroyed.

device :

an NtdDevice based instance

ntd_device_flush ()

void                ntd_device_flush                    (NtdDevice *device,
                                                         gboolean input,
                                                         gboolean output);

Flushes the input queue (if input is TRUE) and/or the output queue (if output is TRUE) on device.

device :

an NtdDevice based instance

input :

whether to flush the input queue

output :

whether to flush the output queue

ntd_device_get_boc ()

gint8               ntd_device_get_boc                  (NtdDevice *device);

Gets the "boc" property of device. Check ntd_device_set_boc() for details on boc and eoc characters.

device :

an NtdDevice based instance

Returns :

the current value of the "boc" property.

ntd_device_get_dump_mode ()

NtdDumpMode         ntd_device_get_dump_mode            (NtdDevice *device);

Gets the current dump mode of device.

device :

an NtdDevice based instance

Returns :

the currently active dump mode.

ntd_device_get_eoc ()

gint8               ntd_device_get_eoc                  (NtdDevice *device);

Gets the "eoc" property of device. Check ntd_device_set_boc() for details on boc and eoc characters.

device :

an NtdDevice based instance

Returns :

the current value of the "eoc" property.

ntd_device_get_error ()

GError *            ntd_device_get_error                (NtdDevice *device);

Gets the device internal error. This function is basically called when catching the errors on a device. Be sure to call ntd_device_clear_error() to reset the internal error after the treatment.

device :

an NtdDevice based instance

Returns :

a GError pointer to the internal error, or NULL if device is not a NtdDevice.

ntd_device_get_file ()

const gchar *       ntd_device_get_file                 (NtdDevice *device);

Retrieves the file name bound to device.

device :

an NtdDevice based instance

Returns :

a pointer to the device file or NULL if there is no associated device. This string points to internally allocated memory and must not be modified or freed.

ntd_device_in_error ()

gboolean            ntd_device_in_error                 (NtdDevice *device);

Checks the presence of internal errors.

device :

an NtdDevice based instance

Returns :

TRUE if the device internal error is set, FALSE otherwise.

ntd_device_is_opened ()

gboolean            ntd_device_is_opened                (NtdDevice *device);

Checks if device is yet opened. This does not mean device is really opened, but that a previous call to ntd_device_open() has been performed.

device :

an NtdDevice based instance

Returns :

TRUE if device is opened, FALSE otherwise

ntd_device_open ()

void                ntd_device_open                     (NtdDevice *device);

Starts the communication over device. If device is in error, no operation is performed.

device :

an NtdDevice based instance

ntd_device_printf ()

gboolean            ntd_device_printf                   (NtdDevice *device,
                                                         const gchar *format,
                                                         ...);

Provides a convenient way to send complex formatted data throught device by using a printf style approach.

format and @... are passed directly to g_vasprintf() so check the GLib manual for further details.

device :

an NtdDevice based instance

format :

printf-style format string

... :

parameters for format string

Returns :

TRUE on success, FALSE on errors or timeout.

ntd_device_read ()

gpointer            ntd_device_read                     (NtdDevice *device,
                                                         gsize nbytes);

Reads nbytes bytes of data from device and returns the result as a newly allocated buffer. If an unexpected condition is encountered before all the nbytes are read (such as a communication timeout), the data is freed and NULL is returned.

If an unexpected condition is encountered, such as a communication timeout, the buffer is freed and NULL is returned. Use another function if partial data are expected.

device :

an NtdDevice based instance

nbytes :

number of bytes to read

Returns :

a newly allocated buffer of nbytes bytes. Dispose the buffer with g_free() when no longer needed.

ntd_device_read_until ()

gpointer            ntd_device_read_until               (NtdDevice *device,
                                                         gchar eol);

Reads I/O data from device until the specified eol terminating character is found. Whatever has been read, including the EOL character, is returned.

The returned buffer could possibly embed NUL bytes and must be freed with g_free() when no longer needed.

If an unexpected condition is encountered, such as a communication timeout, the buffer is freed and NULL is returned. Use another function if partial data are expected.

device :

an NtdDevice based instance

eol :

end-of-line termination character

Returns :

whatever received up to the EOL byte or NULL on errors. Dispose the buffer with g_free() when no longer needed.

ntd_device_set_boc ()

void                ntd_device_set_boc                  (NtdDevice *device,
                                                         gint8 boc);

Sets the "boc" property of device to boc.

"boc" and "eoc" markers are characters used to enclose the hexadecimal value of control (AKA non-printable) characters while in dumping the traffic data. boc and eoc themselves will be considered control characters.

It is sometimes useful to change boc and eoc characters depending on the data expected: it can minimize boc and eoc pollution of the dumped data.

device :

an NtdDevice based instance

boc :

the new Begin Of Control

ntd_device_set_dump_mode ()

void                ntd_device_set_dump_mode            (NtdDevice *device,
                                                         NtdDumpMode dump_mode);

Sets the new dump mode of device to dump_mode.

device :

an NtdDevice based instance

dump_mode :

the new dump mode

ntd_device_set_eoc ()

void                ntd_device_set_eoc                  (NtdDevice *device,
                                                         gint8 eoc);

Sets the "eoc" property of device to eoc. Check ntd_device_set_boc() for details on boc and eoc characters.

device :

an NtdDevice based instance

eoc :

the new End Of Control

ntd_device_set_error ()

void                ntd_device_set_error                (NtdDevice *device,
                                                         NtdSystemError error_code,
                                                         const gchar *format,
                                                         ...);

Sets the device internal error to the specified error code. Optionally, any custom message can be appended to the standard message.

At the end, an "error-set" signal will be emitted.

device :

an NtdDevice based instance

error_code :

an NtdSystemError error code

format :

printf-style format string

... :

parameters for format string

ntd_device_set_error_from_system ()

gboolean            ntd_device_set_error_from_system    (NtdDevice *device,
                                                         const gchar *format,
                                                         ...);

Checks the system for any error and eventually sets the device internal error.

If the device internal error is yet set, the function returns TRUE immediately.

If no system errors are pending, nothing is done and FALSE is returned.

If a system error is present, the device internal error is set accordling to the system error and a ntd_system_clear_error() call is performed to reset the system error. Any custom message can be optionally appended to the standard message.

At the end, an "error-set" signal will be emitted.

device :

an NtdDevice based instance

format :

printf-style format string

... :

parameters for format string

Returns :

TRUE if device is in error or a system error is pending, FALSE otherwise.

ntd_device_set_errorv ()

void                ntd_device_set_errorv               (NtdDevice *device,
                                                         NtdSystemError error_code,
                                                         const gchar *format,
                                                         va_list args);

Wrapper to ntd_device_set_error() with va_list argument.

device :

an NtdDevice based instance

error_code :

the NtdSystemError error code to use

format :

printf-style format string

args :

parameters for format string

ntd_device_set_file ()

void                ntd_device_set_file                 (NtdDevice *device,
                                                         const gchar *file);

Sets the file name of the device bound to device. On posix system, file is usually a file inside the "/dev/" path.

device :

an NtdDevice based instance

file :

the file name

ntd_device_vprintf ()

gboolean            ntd_device_vprintf                  (NtdDevice *device,
                                                         const gchar *format,
                                                         va_list var_args);

A variadic version of ntd_device_printf().

device :

an NtdDevice based instance

format :

printf-style format string

var_args :

va_list of parameters for format string

Returns :

TRUE on success, FALSE on errors or timeout.

ntd_device_write ()

gboolean            ntd_device_write                    (NtdDevice *device,
                                                         gsize nbytes,
                                                         gconstpointer buffer);

Writes nbytes bytes of data from buffer to device.

device :

an NtdDevice based instance

nbytes :

number of bytes to write

buffer :

the source buffer where data come from

Returns :

TRUE if all the data has been sent, FALSE otherwise.

Property Details

The "boc" property

  "boc"                      gchar                 : Read / Write

Control (AKA non-printable) characters will be dumped as hexadecimal values enclosed between #NtdDevice:boc and #NtdDevice:eoc. boc and eoc themselves will be considered control characters.

Default value: 60


The "dump-mode" property

  "dump-mode"                NtdDumpMode           : Read / Write

Dump mode, used to dump traffic I/O for debugging purpose.

Default value: NTD_DUMP_MODE_NONE


The "eoc" property

  "eoc"                      gchar                 : Read / Write

Control (AKA non-printable) characters will be dumped as hexadecimal values enclosed between #NtdDevice:boc and #NtdDevice:eoc. boc and eoc themselves will be considered control characters.

Default value: 62


The "file" property

  "file"                     gchar*                : Read / Write

Device file bound to this device.

Default value: NULL

Signal Details

The "close" signal

void                user_function                      (NtdDevice *device,
                                                        gpointer   user_data)      : No Recursion

Emitted whenever device is closed.

device :

an NtdDevice based instance

user_data :

user data set when the signal handler was connected.

The "error-set" signal

void                user_function                      (NtdDevice *device,
                                                        gpointer   user_data)      : No Recursion

Emitted whenever an I/O call fails.

device :

an NtdDevice based instance

user_data :

user data set when the signal handler was connected.

The "flush" signal

void                user_function                      (NtdDevice *device,
                                                        gboolean   input,
                                                        gboolean   output,
                                                        gpointer   user_data)      : No Recursion

Emitted whenever device must be flushed. One of input or output must be TRUE otherwise the internal error will be set.

device :

an NtdDevice based instance

input :

whether to flush the input queue

output :

whether to flush the output queue

user_data :

user data set when the signal handler was connected.

The "open" signal

void                user_function                      (NtdDevice *device,
                                                        gpointer   user_data)      : No Recursion

Emitted whenever device is opened. On success, the internal is-opened state is set to TRUE. If yet set, that is if device has been opened before, no actions are taken.

device :

an NtdDevice based instance

user_data :

user data set when the signal handler was connected.

The "read" signal

guint               user_function                      (NtdDevice *device,
                                                        guint      nbytes,
                                                        gpointer   buffer,
                                                        gpointer   user_data)      : No Recursion

Emitted whenever a read operation, that is a call to the raw_read() virtual method, is performed.

device :

an NtdDevice based instance

nbytes :

number of bytes read

buffer :

pointer to the destination memory

user_data :

user data set when the signal handler was connected.

Returns :

the number of bytes effectively read.

The "write" signal

guint               user_function                      (NtdDevice *device,
                                                        guint      nbytes,
                                                        gpointer   buffer,
                                                        gpointer   user_data)      : No Recursion

Emitted whenever a write operation, that is a call to the raw_write() virtual method, is performed.

device :

an NtdDevice based instance

nbytes :

number of bytes written

buffer :

pointer to the source memory

user_data :

user data set when the signal handler was connected.

Returns :

the number of bytes effectively written.