Socket Addresses.

Name

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

Synopsis



struct      GskSocketAddressClass;
struct      GskSocketAddress;
struct      GskSocketAddressIpv4;
struct      GskSocketAddressLocal;
struct      GskSocketAddressIpv6;
GskSocketAddress* gsk_socket_address_from_native
                                            (gconstpointer native_data,
                                             guint 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_new_local
                                            (const char *path);
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

struct GskSocketAddressClass

struct GskSocketAddressClass {

  GObjectClass object_class;
  guint 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,
			  guint             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);
};

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.

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

gboolean (*to_native) (GskSocketAddress *address, gpointer output)

Convert to a native struct sockaddr* type representation.

gboolean (*from_native) (GskSocketAddress *address, gconstpointer sockaddr_data, guint sockaddr_length)

Convert from a native struct sockaddr* type representation.

char* (*to_string) (GskSocketAddress *address)

Convert to a human-readable ASCII representation.

gboolean (*equals) (GskSocketAddress *addr1, GskSocketAddress *addr2)

Test if this is equal to another GskSocketAddress of this exact type are equal.

guint (*hash) (GskSocketAddress *addr)

Compute a hash-value based on this socket.


struct GskSocketAddress

struct GskSocketAddress;

The base instance for all socket addresses.


struct GskSocketAddressIpv4

struct GskSocketAddressIpv4;

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


struct GskSocketAddressLocal

struct GskSocketAddressLocal;

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


struct GskSocketAddressIpv6

struct GskSocketAddressIpv6;

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


gsk_socket_address_from_native ()

GskSocketAddress* gsk_socket_address_from_native
                                            (gconstpointer native_data,
                                             guint 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_new_local ()

GskSocketAddress* gsk_socket_address_new_local
                                            (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_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.