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

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

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

Generated by GTK-Doc V1.11