gnome-string-socket

Gnome Socket Library Reference Manual
<<< Previous Page	Home	Up

Description

A gnome-socket can provide convenient network I/O, but if the data stream is line-oriented this can be still not enough. In fact, if the remote peer sends the strings "AAAA\n", "BBB\n" and "CCCCCC\n" we could receive them in a single read from the socket as "AAAA\nBBB\nCCCCCC\n" but we could receive "AA" in the first read, "AA\nB" in the second and "BB\nCCCCCC\n" in the third. This in most cases forces us to use a buffer to handle the half-line reads and the multi-line reads and similar cases. Remember that gnome-socket calls the callback whenever there's pending data from the socket.

A gnome-string-socket instead calls the callback only when there's a single full line ready (i.e. fully received from the socket) or in order to notify special cases (e.g. network errors, ). This means that if "A\nB\nC\n" is received from the socket the callback will be called three times. Moreover, the callback receives directly the string and doesn't have to read from the socket (i.e. from the GIOChannel): in the previous case tha callback would have been called with "A", with "B" and then with "C". Note that gnome-string-socket strips the "\n" away for you and terminates the string with '\0'.

Details

GnomeStringSocketCallback ()

void        (*GnomeStringSocketCallback)    (guint tag,
                                             GnomeSocketInfo info,
                                             gint extra_info,
                                             GIOChannel *channel,
                                             gchar *str,
                                             gpointer data);

A callback passed to gnome_string_socket_connect() or gnome_string_socket_listen() can be called for many different reasons. Please note that you should _not_ read from channel but only write to it: moreover you are responsible to add the end-of-line when necessary. This also means that you can write three messages simply writing "A\nB\nC\n".

The info parameter explains why the callback has been called. Read the GnomeSocketCallback for the meaning of info. In addition, the following further cases are contempled:

If info is GNOME_SOCKET_READ_ERROR an error occoured reading from the socket. extra_info contains the errno value from libc and explains why the error occoured. In any case, you should call gnome_string_socket_close() after an error to free resources.

If info is GNOME_SOCKET_CLOSED the remote peer ha closed the connection. Call gnome_string_socket_close() to do free resources.

`tag` :	a gnome_string_socket tag.
`info` :	socket status.
`extra_info` :	general purpose parameter. See above and gnome_socket.
`channel` :	this can be used to do network I/O with g_io_channel_write(). (write only!)
`str` :	the string read from the socket (you must duplicate it if you want to use it outside the callback).
`data` :	the user data that was passed to gnome_string_socket_connect() or gnome_string_socket_listen()

gnome_string_socket_connect ()

guint       gnome_string_socket_connect     (const gchar *hostname,
                                             GnomeNetAddressType addr_type,
                                             guint port,
                                             const gchar *delim,
                                             GnomeStringSocketCallback callback,
                                             gpointer callback_data);

Contacts a remote host at a specified port, calling the callback to notify anything interesting. Please note: if gnome-socket was compiled with --with-resolver-lib=gnome this function could call the callback immediately in certain cases.

`hostname` :	the name of the host to contact
`addr_type` :	this must be `GNOME_NET_ADDRESS_INET4` for now.
`port` :	the destination port.
`delim` :	a string of the characters that should be considered end-of-line. In most cases, this will be "\n".
`callback` :	the function to call when dns lookup has been performed, when connection has been established (or a network error occoured), when a single full line has been received from the net and when the connection has been closed. See GnomeStringSocketCallback for more info.
`callback_data` :	the user data that will be passed whenever the `callback` is called.
Returns :	a gnome_string_socket tag (0 in case of error).

gnome_string_socket_listen ()

guint       gnome_string_socket_listen      (guint port,
                                             const gchar *delim,
                                             GnomeStringSocketCallback callback,
                                             gpointer callback_data,
                                             GnomeSocketInfo *info,
                                             gint *error_no);

Opens a socket awaiting for incoming connections on a port.

`port` :	the local port.
`delim` :	a string of the characters that should be considered end-of-line. In most cases, this will be "\n".
`callback` :	the function to call when there's an incoming connection (or a network error occoured), when a single full line has been received from the net and when the connection has been closed. See GnomeStringSocketCallback for more info.
`callback_data` :	the user data that will be passed whenever the `callback` is called.
`info` :	this must point to a valid allocated zone, and it's used to report errors to the caller. If *`info` is not `GNOME_SOCKET_OK` it identifies what system call failed.
`error_no` :	this must point to a valid allocated zone, and it's equal to libc errno. If *`info` is not `GNOME_SOCKET_OK` this identifies why the system call failed.
Returns :	a gnome_string_socket tag (0 in case of error).

gnome_string_socket_close ()

gboolean    gnome_string_socket_close       (guint tag);

Closes an active connection or stops listening for incoming connections. Note that a socket is never closed automatically (even if an error occoured) and therefore you must call gnome_string_socket_close() to free resources.

`tag` :	a gnome_string_socket tag created by gnome_string_socket_connect() or gnome_string_socket_listen().
Returns :	`TRUE` on success, `FALSE` otherwise (i.e. invalid tag).