Socket Addresses.

Socket Addresses. — The location of a socket endpoint, in some domain.

Synopsis




            GskSocketAddressClass;
            GskSocketAddress;
            GskSocketAddressIpv4;
            GskSocketAddressLocal;
            GskSocketAddressIpv6;
            GskSocketAddressEthernet;
GskSocketAddress* gsk_socket_address_from_native
                                            (gconstpointer native_data,
                                             gsize native_size);
gint        gsk_socket_address_protocol_family
                                            (GskSocketAddress *address);
gint        gsk_socket_address_address_family
                                            (GskSocketAddress *address);
guint       gsk_socket_address_sizeof_native
                                            (GskSocketAddress *address);
gboolean    gsk_socket_address_to_native    (GskSocketAddress *address,
                                             gpointer output,
                                             GError **error);
char*       gsk_socket_address_to_string    (GskSocketAddress *address);
#define     gsk_socket_address_ipv4_localhost(port)
GskSocketAddress* gsk_socket_address_ipv4_new
                                            (const guint8 *ip_address,
                                             guint16 port);
GskSocketAddress* gsk_socket_address_ipv6_new
                                            (const guint8 *address,
                                             guint16 port);
GskSocketAddress* gsk_socket_address_ethernet_new
                                            (const guint8 *mac_addr);
GskSocketAddress* gsk_socket_address_local_new
                                            (const char *path);
gboolean    gsk_socket_address_system_supports_ipv6
                                            (void);
void        gsk_socket_address_register_subclass
                                            (GskSocketAddressClass *klass);
int         gsk_socket_address_connect_fd   (GskSocketAddress *address,
                                             gboolean *is_connected,
                                             GError **error);
gboolean    gsk_socket_address_finish_fd    (int fd,
                                             GError **error);
gboolean    gsk_socket_address_equals       (gconstpointer address_a_ptr,
                                             gconstpointer address_b_ptr);
guint       gsk_socket_address_hash         (gconstpointer address_ptr);
#define     GSK_SOCKET_ADDRESS_REMOTE_QUARK
#define     GSK_SOCKET_ADDRESS_LOCAL_QUARK

Object Hierarchy


  GObject
   +----GskSocketAddress
         +----GskSocketAddressIpv4
         +----GskSocketAddressIpv6
         +----GskSocketAddressLocal


  GObject
   +----GskSocketAddress
         +----GskSocketAddressIpv4


  GObject
   +----GskSocketAddress
         +----GskSocketAddressLocal


  GObject
   +----GskSocketAddress
         +----GskSocketAddressIpv6

Description

This is a GObject equivalent of sockaddr_t.

Details

GskSocketAddressClass

typedef struct {
  GObjectClass object_class;
  gsize sizeof_native_address;
  gint protocol_family;		/* eg PF_INET, PF_LOCAL etc */
  gint address_family;		/* eg AF_INET, AF_LOCAL etc */
  gboolean (*to_native)  (GskSocketAddress *address,
			  gpointer          output);
  gboolean (*from_native)(GskSocketAddress *address,
			  gconstpointer     sockaddr_data,
			  gsize             sockaddr_length);
  char    *(*to_string)  (GskSocketAddress *address);
  /* note: both addresses will be of exactly the same type */
  gboolean (*equals)     (GskSocketAddress *addr1,
			  GskSocketAddress *addr2);
  guint    (*hash)       (GskSocketAddress *addr);
} GskSocketAddressClass;

The base-class for all types of socket-addresses. The members of this class should only be used by derived classes.

GObjectClass object_class; the base-class.
gsize sizeof_native_address; how big is a socket-address of this type in the native OS representation.
gint protocol_family; native PF_* macro value for this type of address.
gint address_family; native AF_* macro value for this type of address.
to_native () Convert to a native struct sockaddr* type representation.
from_native () Convert from a native struct sockaddr* type representation.
to_string () Convert to a human-readable ASCII representation.
equals () Test if this is equal to another GskSocketAddress of this exact type are equal.
hash () Compute a hash-value based on this socket.

GskSocketAddress

typedef struct _GskSocketAddress GskSocketAddress;

The base instance for all socket addresses.

GskSocketAddressIpv4

typedef struct _GskSocketAddressIpv4 GskSocketAddressIpv4;

An IPv4 Socket Address. This is a 4-byte host IP address and a 2-byte port number (as a guint16).

GskSocketAddressLocal

typedef struct _GskSocketAddressLocal GskSocketAddressLocal;

A local socket, often called a UNIX-domain socket.

GskSocketAddressIpv6

typedef struct _GskSocketAddressIpv6 GskSocketAddressIpv6;

An IPv6 Socket Address. For now, the IPv6 implementation is unfinished.

GskSocketAddressEthernet

typedef struct {
  GskSocketAddress      socket_address;
  guint8                mac_address[6];
} GskSocketAddressEthernet;

gsk_socket_address_from_native ()

GskSocketAddress* gsk_socket_address_from_native
                                            (gconstpointer native_data,
                                             gsize native_size);

Allocate a new GskSocketAddress based on native_data, if we know how.

native_data : a struct sockaddr_t*.
native_size : length of native_data.
Returns : a new GskSocketAddress or NULL if we could not interpret the sockaddr.

gsk_socket_address_protocol_family ()

gint        gsk_socket_address_protocol_family
                                            (GskSocketAddress *address);

Get the PF_* macro value corresponding to this address.

address : a socket address.
Returns : the protocol family.

gsk_socket_address_address_family ()

gint        gsk_socket_address_address_family
                                            (GskSocketAddress *address);

Get the AF_* macro value corresponding to this address.

address : a socket address.
Returns : the address family.

gsk_socket_address_sizeof_native ()

guint       gsk_socket_address_sizeof_native
                                            (GskSocketAddress *address);

Determine how many bytes of storage the sockaddr_t based on this object will require.

address : a socket address.
Returns : the size in bytes of the native sockaddr type.

gsk_socket_address_to_native ()

gboolean    gsk_socket_address_to_native    (GskSocketAddress *address,
                                             gpointer output,
                                             GError **error);

Convert a socket-address to its native form.

address : a socket address.
output : a struct sockaddr_t (at least conceptually)
error : optional error return value.
Returns : whether it was able to convert the address.

gsk_socket_address_to_string ()

char*       gsk_socket_address_to_string    (GskSocketAddress *address);

Convert a socket-address to a newly allocated string, which the caller must free.

address : a socket address.
Returns : a string for the user to free.

gsk_socket_address_ipv4_localhost()

#define     gsk_socket_address_ipv4_localhost(port)

Create a new address pointing to this host, on the given port.

port : the port on the local host the address should refer to.
Returns : the newly allocated GskSocketAddressIpv4.

gsk_socket_address_ipv4_new ()

GskSocketAddress* gsk_socket_address_ipv4_new
                                            (const guint8 *ip_address,
                                             guint16 port);

Allocate a new IPv4 address given a numeric IP and port number.

ip_address : the 4-byte IP address
port : the port number.
Returns : a new GskSocketAddress

gsk_socket_address_ipv6_new ()

GskSocketAddress* gsk_socket_address_ipv6_new
                                            (const guint8 *address,
                                             guint16 port);

address :
port :
Returns :

gsk_socket_address_ethernet_new ()

GskSocketAddress* gsk_socket_address_ethernet_new
                                            (const guint8 *mac_addr);

Allocate a new socket address corresponding to an ethernet device.

mac_addr : the 6-byte unique address of this ethernet device.
Returns : the newly allocated socket-address.

gsk_socket_address_local_new ()

GskSocketAddress* gsk_socket_address_local_new
                                            (const char *path);

Create a socket-address which is associated with a path in the local filesystem. Such socket-addresses are useful for fast communication between processes on the same host.

Sometimes, these types of addresses are called unix-domain addresses, but it is better to avoid the term unix for a generic concept.

path : path in filesystem to hook this socket up.
Returns : the newly allocated socket address.

gsk_socket_address_system_supports_ipv6 ()

gboolean    gsk_socket_address_system_supports_ipv6
                                            (void);

Returns :

gsk_socket_address_register_subclass ()

void        gsk_socket_address_register_subclass
                                            (GskSocketAddressClass *klass);

Add the class to a per address-family hash table for use converting from native.

klass : a concrete derived class.

gsk_socket_address_connect_fd ()

int         gsk_socket_address_connect_fd   (GskSocketAddress *address,
                                             gboolean *is_connected,
                                             GError **error);

Begin connecting to a location by address.

If the connection is fully established before returning to the caller, then *is_connected will be set to TRUE and a non-negative file descriptor will be returned.

Sometimes connections only partially succeed, in which case *is_connected will be set to FALSE, and you must call gsk_socket_address_finish_fd() whenever the file-description polls ready to input or output.

If the connect fails immediately, -1 will be returned and *error will be set if error is non-NULL.

address : the address to connect to.
is_connected : whether the connection succeeded completely.
error : an optional error return.
Returns : the connecting or connected file-descriptor, or -1 on error.

gsk_socket_address_finish_fd ()

gboolean    gsk_socket_address_finish_fd    (int fd,
                                             GError **error);

Finish connecting a partially connected file-descriptor.

fd : a file descriptor which may be done connecting.
error : an optional error return.
Returns : TRUE if the connection is now established, otherwise it returns FALSE and will set *error if an error occurred.

gsk_socket_address_equals ()

gboolean    gsk_socket_address_equals       (gconstpointer address_a_ptr,
                                             gconstpointer address_b_ptr);

This function is a GEqualFunc which can determine if two socket address are the same. This is principally used with gsk_socket_address_hash to make a hash-table mapping from socket-addresses.

(This just uses the virtual method of GskSocketAddressClass)

address_a_ptr : a pointer to a GskSocketAddress.
address_b_ptr : a pointer to a GskSocketAddress.
Returns : whether the addresses are equal.

gsk_socket_address_hash ()

guint       gsk_socket_address_hash         (gconstpointer address_ptr);

This function is a GHashFunc which can determine a hash value for a socket-address.

This is principally used with gsk_socket_address_equals to make a hash-table mapping from socket-addresses.

(This just uses the virtual method of GskSocketAddressClass)

address_ptr : a pointer to a GskSocketAddress.
Returns : the hash value for the socket-address.

GSK_SOCKET_ADDRESS_REMOTE_QUARK

#define GSK_SOCKET_ADDRESS_REMOTE_QUARK	(gsk_socket_address_get_remote_quark())

Used with g_object_set_qdata() to store the remote-address of a stream.

GSK_SOCKET_ADDRESS_LOCAL_QUARK

#define GSK_SOCKET_ADDRESS_LOCAL_QUARK	(gsk_socket_address_get_local_quark())

Used with g_object_set_qdata() to store the local-address of a stream.