## 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.