Gnome Socket Library Reference Manual
<<< Previous PageHomeUpNext Page >>>

gnome-socket

Name

gnome-socket -- a network socket abstraction.

Synopsis



enum        GnomeNetProtocol;
enum        GnomeSocketInfo;
void        (*GnomeSocketCallback)          (guint tag,
                                             GnomeSocketInfo info,
                                             gint extra_info,
                                             GIOChannel *channel,
                                             gpointer data);
guint       gnome_socket_connect            (const gchar *hostname,
                                             GnomeNetAddressType addr_type,
                                             GnomeNetProtocol proto,
                                             guint port,
                                             GnomeSocketCallback callback,
                                             gpointer callback_data);
guint       gnome_socket_listen             (GnomeNetProtocol proto,
                                             guint port,
                                             GnomeSocketCallback callback,
                                             gpointer callback_data,
                                             GnomeSocketInfo *info,
                                             gint *error_no);
GnomeNetAddress* gnome_socket_get_addr      (guint tag);
guint       gnome_socket_get_port           (guint tag);
GnomeSocketCallback gnome_socket_get_callback
                                            (guint tag);
gboolean    gnome_socket_set_callback       (guint tag,
                                             GnomeSocketCallback callback);
gpointer    gnome_socket_get_callback_data  (guint tag);
gboolean    gnome_socket_set_callback_data  (guint tag,
                                             gpointer callback_data);
gboolean    gnome_socket_close              (guint tag);

Description

A gnome-socket can be used both for connecting to remote hosts and listening for incoming connections from remote hosts. When a network event happens (e.g. connection has been established, data has arrived, network errors occoured, etc.) a user callback is called in order to notify it.

Please note that currently this document describes TCP sockets only.

Outgoing connections.

When gnome_socket_connect() is called a connecting socket is created and dns lookup is started. When the lookup completes the callback is called (the application might want to change a status bar from "Looking up..." to "Connecting to..."). If the lookup was successful and the callback returned without closing the socket, the connection is started. Again, when the connection is established the callback is called (the application can now send data). Now the socket is connected and you can read/write to the socket at any moment. To permit non-blocking reading, the callback will be called when there's data pending. To close the socket simply call gnome_socket_close().

Please note that dns lookup will not abort on timeout: if you need a timeout you can install a timeout callback with g_timeout_add() provided by Glib.

Incoming connections.

When gnome_socket_listen() is called a listening socket is created. When a new incoming connection has been established the callback is called with the tag of the listening socket, the tag of the new connected socket of the new connection and a GIOChannel. The application can now do I/O and, like outgoing connections, the callback will be called again when there's data pending which can be read. Note that a listening socket can accept several incoming connections, since every time a new tag is reported. If you don't need this, you can simply close the listening socket at the first incoming connection. In any case, close the listening socket to stop accepting new connections and close the connected sockets to close previously established connections.

Details

enum GnomeNetProtocol

typedef enum {
  GNOME_NET_PROTOCOL_TCP = 0,
  GNOME_NET_PROTOCOL_UDP = 1
} GnomeNetProtocol;

Protocols supported by gnome_socket.

enum GnomeSocketInfo

typedef enum {
  GNOME_SOCKET_OK             = 0,   /* OK */
  GNOME_SOCKET_JUST_RESOLVED  = 1,   /* DNS lookup succeeded */
  GNOME_SOCKET_JUST_CONNECTED = 2,   /* comm has just been established */
  GNOME_SOCKET_DNS_ERROR      = 3,   /* DNS lookup failed */
  GNOME_SOCKET_SOCKET_ERROR   = 4,   /* socket() failed */
  GNOME_SOCKET_BIND_ERROR     = 5,   /* bind() failed */
  GNOME_SOCKET_LISTEN_ERROR   = 6,   /* listen() failed */
  GNOME_SOCKET_ACCEPT_ERROR   = 7,   /* accept() failed */
  GNOME_SOCKET_CONNECT_ERROR  = 8,   /* connect() failed */
  GNOME_SOCKET_FCNTL_ERROR    = 9,   /* fcntl() failed */
  GNOME_SOCKET_INVALID_PROTO  = 10,  /* invalid parameter */
  /* the following are reserved for higher level abstractions */
  GNOME_SOCKET_READ_ERROR     = 100, /* read() failed */
  GNOME_SOCKET_WRITE_ERROR    = 101, /* write() failed */
  GNOME_SOCKET_CLOSED         = 102  /* remote host has closed the socket */
} GnomeSocketInfo;

A type representing the status of the socket.

GnomeSocketCallback ()

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

A callback passed to gnome_socket_connect() or gnome_socket_listen() can be called for many different reasons. The info parameter explains why the callback has been called.

Outgoing connections.

If info is GNOME_SOCKET_JUST_RESOLVED the dns lookup has been completed successfully. You could want to show this to the user (changing the status bar from "Looking up..." to "Contacting...", for instance). Calling gnome_socket_get_address() will get the resolved IP address.

If info is GNOME_SOCKET_JUST_CONNECTED the remote host has been contacted. It's now possible to send data to the remote host writing to channel. Usually the callback will also save channel somewhere in order to use it later from other functions. extra_info is equal to tag for analogy to incoming connections (you are not meant to understand the rationale for this now).

If info is GNOME_SOCKET_OK there's incoming data to read from channel or the connection has been closed by the remote host. If reading from channel yelds zero bytes we are in the second case.

If info is GNOME_SOCKET_DNS_ERROR dns lookup failed. If info is GNOME_SOCKET_CONNECT_ERROR the remote host couldn't be contacted. extra_info contains the errno value from libc and explains why the error occoured (see connect(2) for more info). In any case, you should call gnome_socket_close() after an error to free resources.

Incoming connections.

If info is GNOME_SOCKET_JUST_CONNECTED a new connection has been established. Please note that in this case tag is the tag of the listening socket while extra_info is a tag of a new (connected) socket. It's now possible to send data to the remote host writing to channel (that is the channel related with the tag in extra_info -- listening sockets never have related channels). Usually the callback will save both extra_info and channel somewhere in order to use them later from other functions. Moreover, from now on the callback should be prepared to be called with tag set to the tag of the new socket (extra_info) when there's incoming data to read from the socket or when the connection has been closed by the remote host (if you don't like this behaviour you can override it with gnome_socket_set_callback() on the new tag extra_info). At any time, calling gnome_socket_close() with the extra_info tag will close the new connection, while calling gnome_socket_close() with tag will stop accepting incoming connections. This means that if the application handles only one incoming connection should close the listening socket with gnome_socket_close(tag) now.

If info is GNOME_SOCKET_OK there's incoming data to read from channel or the connection has been closed by the remote host. If reading from channel yelds zero bytes we are in the second case.

tag :a gnome_socket tag.
info :socket status.
extra_info :general purpose parameter. See above.
channel :this can be used to do network I/O with g_io_channel_read/write().
data :the user data that was passed to gnome_socket_connect() or gnome_socket_listen()

gnome_socket_connect ()

guint       gnome_socket_connect            (const gchar *hostname,
                                             GnomeNetAddressType addr_type,
                                             GnomeNetProtocol proto,
                                             guint port,
                                             GnomeSocketCallback 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.
proto :the network protocol (like GNOME_NET_PROTOCOL_TCP or GNOME_NET_PROTOCOL_UDP).
port :the destination port (if applicable to the protocol).
callback :the function to call when dns lookup has been performed, when connection has been established (or a network error occoured), when data has been received from the net and when the connection has been closed. See GnomeSocketCallback for more info.
callback_data :the user data that will be passed whenever the callback is called.
Returns :a gnome_socket tag (0 in case of error).

gnome_socket_listen ()

guint       gnome_socket_listen             (GnomeNetProtocol proto,
                                             guint port,
                                             GnomeSocketCallback callback,
                                             gpointer callback_data,
                                             GnomeSocketInfo *info,
                                             gint *error_no);

Opens a socket awaiting for incoming connections on a port.

proto :the network protocol (like GNOME_NET_PROTOCOL_TCP or GNOME_NET_PROTOCOL_UDP).
port :the local port (if applicable to the protocol).
callback :the function to call when there's an incoming connection (or a network error occoured), when data has been received from the net and when the connection has been closed. See GnomeSocketCallback 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_socket tag (0 in case of error).

gnome_socket_get_addr ()

GnomeNetAddress* gnome_socket_get_addr      (guint tag);

Gets the socket remote address.

tag :a gnome_socket tag created by gnome_socket_connect() or gnome_socket_listen().
Returns :the address of the other end or NULL if not applicable (e.g. the socket is listening). The caller must call gnome_net_address_destroy() when it isn't needed anymore.

gnome_socket_get_port ()

guint       gnome_socket_get_port           (guint tag);

Gets the socket remote or local port.

tag :a gnome_socket tag created by gnome_socket_connect() or gnome_socket_listen().
Returns :if the socket is listening it returns the local port, if the socket is connecting/ed it returns the remote port. It returns 0 if not applicable.

gnome_socket_get_callback ()

GnomeSocketCallback gnome_socket_get_callback
                                            (guint tag);

Gets the callback that is used to report network events related to this socket.

tag :a gnome_socket tag created by gnome_socket_connect() or gnome_socket_listen().
Returns :the callback pointer or NULL in case of error (i.e. invalid tag).

gnome_socket_set_callback ()

gboolean    gnome_socket_set_callback       (guint tag,
                                             GnomeSocketCallback callback);

Changes the callback that is used to report network events related to this socket. The old one will never be called (for this socket).

tag :a gnome_socket tag created by gnome_socket_connect() or gnome_socket_listen().
callback :the callback pointer.
Returns :TRUE on success, FALSE otherwise (i.e. invalid tag).

gnome_socket_get_callback_data ()

gpointer    gnome_socket_get_callback_data  (guint tag);

Gets what will be passed to the callback when it will be called.

tag :a gnome_socket tag created by gnome_socket_connect() or gnome_socket_listen().
Returns :the data pointer or NULL if an error occoured. Unlike gnome_get_callback() NULL could be a valid data value and therefore (if data was previously set to NULL) it's impossible to know if an error occoured because the tag was not valid. As in other functions, an error message is printed on the console since it reveals a bug of the application.

gnome_socket_set_callback_data ()

gboolean    gnome_socket_set_callback_data  (guint tag,
                                             gpointer callback_data);

Changes the data that will be passed to the callback.

tag :a gnome_socket tag created by gnome_socket_connect() or gnome_socket_listen().
callback_data :the data pointer.
Returns :TRUE on success, FALSE otherwise (i.e. invalid tag).

gnome_socket_close ()

gboolean    gnome_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_socket_close() to free resources.

tag :a gnome_socket tag created by gnome_socket_connect() or gnome_socket_listen().
Returns :TRUE on success, FALSE otherwise (i.e. invalid tag).



<<< Previous PageHomeUpNext Page >>>
gnome-net-addressgnome-string-socket