plibsys
Typedefs | Enumerations | Functions
psocketaddress.h File Reference

Socket address wrapper. More...

#include <pmacros.h>
#include <ptypes.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
Include dependency graph for psocketaddress.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef P_BEGIN_DECLS enum PSocketFamily_ PSocketFamily
 Socket address family. More...
 
typedef struct PSocketAddress_ PSocketAddress
 Socket address opaque structure. More...
 

Enumerations

enum  PSocketFamily_ { P_SOCKET_FAMILY_UNKNOWN = 0, P_SOCKET_FAMILY_INET = AF_INET, P_SOCKET_FAMILY_INET6 = -1 }
 Socket address family. More...
 

Functions

P_LIB_API PSocketAddressp_socket_address_new_from_native (pconstpointer native, psize len)
 Creates new PSocketAddress from the native socket address raw data. More...
 
P_LIB_API PSocketAddressp_socket_address_new (const pchar *address, puint16 port)
 Creates new PSocketAddress. More...
 
P_LIB_API PSocketAddressp_socket_address_new_any (PSocketFamily family, puint16 port)
 Creates new PSocketAddress for the any-address representation. More...
 
P_LIB_API PSocketAddressp_socket_address_new_loopback (PSocketFamily family, puint16 port)
 Creates new PSocketAddress for the loopback interface. More...
 
P_LIB_API pboolean p_socket_address_to_native (const PSocketAddress *addr, ppointer dest, psize destlen)
 Converts PSocketAddress to the native socket address raw data. More...
 
P_LIB_API psize p_socket_address_get_native_size (const PSocketAddress *addr)
 Gets the size of the native socket address raw data, in bytes. More...
 
P_LIB_API PSocketFamily p_socket_address_get_family (const PSocketAddress *addr)
 Gets a family of a socket address. More...
 
P_LIB_API pcharp_socket_address_get_address (const PSocketAddress *addr)
 Gets a socket address in a string representation, i.e. More...
 
P_LIB_API puint16 p_socket_address_get_port (const PSocketAddress *addr)
 Gets a port number of a socket address. More...
 
P_LIB_API puint32 p_socket_address_get_flow_info (const PSocketAddress *addr)
 Gets IPv6 traffic class and flow information. More...
 
P_LIB_API puint32 p_socket_address_get_scope_id (const PSocketAddress *addr)
 Gets an IPv6 set of interfaces for a scope. More...
 
P_LIB_API void p_socket_address_set_flow_info (PSocketAddress *addr, puint32 flowinfo)
 Sets IPv6 traffic class and flow information. More...
 
P_LIB_API void p_socket_address_set_scope_id (PSocketAddress *addr, puint32 scope_id)
 Sets an IPv6 set of interfaces for a scope. More...
 
P_LIB_API pboolean p_socket_address_is_flow_info_supported (void)
 Checks whether flow information is supported in IPv6. More...
 
P_LIB_API pboolean p_socket_address_is_scope_id_supported (void)
 Checks whether a set of interfaces for a scope is supported in IPv6. More...
 
P_LIB_API pboolean p_socket_address_is_ipv6_supported (void)
 Checks whether IPv6 protocol is supported. More...
 
P_LIB_API pboolean p_socket_address_is_any (const PSocketAddress *addr)
 Checks whether a given socket address is an any-address representation. More...
 
P_LIB_API pboolean p_socket_address_is_loopback (const PSocketAddress *addr)
 Checks whether a given socket address is for the loopback interface. More...
 
P_LIB_API void p_socket_address_free (PSocketAddress *addr)
 Frees a socket address structure and its resources. More...
 

Detailed Description

Socket address wrapper.

Author
Alexander Saprykin

A socket address is usually represented by a network address (IPv4 or IPv6) and a port number (though some other naming schemes and parameters are possible).

Socket address parameters are stored inside a special system (native) structure in the binary (raw) form. The native structure varies with an operating system and a network protocol. PSocketAddress acts like a thin wrapper around that native address structure and unifies manipulation of socket address data.

PSocketAddress supports IPv4 and IPv6 addresses which consist of an IP address and a port number. IPv6 support is system dependent and not provided for all the platforms. Sometimes you may also need to enable IPv6 support in the system to make it working.

Convenient methods to create special addresses are provided: for the loopback interface use p_socket_address_new_loopback(), for the any-address interface use p_socket_address_new_any().

If you want to get the underlying native address structure for further usage in system calls use p_socket_address_to_native(), and p_socket_address_new_from_native() for a vice versa conversion.

Typedef Documentation

◆ PSocketAddress

typedef struct PSocketAddress_ PSocketAddress

Socket address opaque structure.

◆ PSocketFamily

Socket address family.

Enumeration Type Documentation

◆ PSocketFamily_

Socket address family.

Enumerator
P_SOCKET_FAMILY_UNKNOWN 

Unknown family.

P_SOCKET_FAMILY_INET 

IPv4 family.

P_SOCKET_FAMILY_INET6 

No IPv6 family.

Function Documentation

◆ p_socket_address_free()

P_LIB_API void p_socket_address_free ( PSocketAddress addr)

Frees a socket address structure and its resources.

Parameters
addrPSocketAddress to free.
Since
0.0.1

◆ p_socket_address_get_address()

P_LIB_API pchar* p_socket_address_get_address ( const PSocketAddress addr)

Gets a socket address in a string representation, i.e.

"172.146.45.5".

Parameters
addrPSocketAddress to get address string for.
Returns
Pointer to the string representation of the socket address in case of success, NULL otherwise. The caller takes ownership of the returned pointer.
Since
0.0.1

◆ p_socket_address_get_family()

P_LIB_API PSocketFamily p_socket_address_get_family ( const PSocketAddress addr)

Gets a family of a socket address.

Parameters
addrPSocketAddress to get the family for.
Returns
PSocketFamily of the socket address.
Since
0.0.1

◆ p_socket_address_get_flow_info()

P_LIB_API puint32 p_socket_address_get_flow_info ( const PSocketAddress addr)

Gets IPv6 traffic class and flow information.

Parameters
addrPSocketAddress to get flow information for.
Returns
IPv6 traffic class and flow information.
Since
0.0.1
Note
This call is valid only for an IPv6 address, otherwise 0 is returned.
Some operating systems may not support this property.
See also
p_socket_address_is_flow_info_supported()

◆ p_socket_address_get_native_size()

P_LIB_API psize p_socket_address_get_native_size ( const PSocketAddress addr)

Gets the size of the native socket address raw data, in bytes.

Parameters
addrPSocketAddress to get the size of native address raw data for.
Returns
Size of the native socket address raw data in case of success, 0 otherwise.
Since
0.0.1

◆ p_socket_address_get_port()

P_LIB_API puint16 p_socket_address_get_port ( const PSocketAddress addr)

Gets a port number of a socket address.

Parameters
addrPSocketAddress to get the port number for.
Returns
Port number in case of success, 0 otherwise.
Since
0.0.1

◆ p_socket_address_get_scope_id()

P_LIB_API puint32 p_socket_address_get_scope_id ( const PSocketAddress addr)

Gets an IPv6 set of interfaces for a scope.

Parameters
addrPSocketAddress to get the set of interfaces for.
Returns
Index that identifies the set of interfaces for a scope.
Since
0.0.1
Note
This call is valid only for an IPv6 address, otherwise 0 is returned.
Some operating systems may not support this property.
See also
p_socket_address_is_scope_id_supported()

◆ p_socket_address_is_any()

P_LIB_API pboolean p_socket_address_is_any ( const PSocketAddress addr)

Checks whether a given socket address is an any-address representation.

Such an address is a 0.0.0.0.

Parameters
addrPSocketAddress to check.
Returns
TRUE if the addr is the any-address representation, FALSE otherwise.
Since
0.0.1
See also
p_socket_address_new_any()

◆ p_socket_address_is_flow_info_supported()

P_LIB_API pboolean p_socket_address_is_flow_info_supported ( void  )

Checks whether flow information is supported in IPv6.

Returns
TRUE in case of success, FALSE otherwise.
Since
0.0.1

◆ p_socket_address_is_ipv6_supported()

P_LIB_API pboolean p_socket_address_is_ipv6_supported ( void  )

Checks whether IPv6 protocol is supported.

Returns
TRUE in case of success, FALSE otherwise.
Since
0.0.3

◆ p_socket_address_is_loopback()

P_LIB_API pboolean p_socket_address_is_loopback ( const PSocketAddress addr)

Checks whether a given socket address is for the loopback interface.

Such an address is a 127.x.x.x.

Parameters
addrPSocketAddress to check.
Returns
TRUE if the addr is for the loopback interface, FALSE otherwise.
Since
0.0.1
See also
p_socket_address_new_loopback()

◆ p_socket_address_is_scope_id_supported()

P_LIB_API pboolean p_socket_address_is_scope_id_supported ( void  )

Checks whether a set of interfaces for a scope is supported in IPv6.

Returns
TRUE in case of success, FALSE otherwise.
Since
0.0.1

◆ p_socket_address_new()

P_LIB_API PSocketAddress* p_socket_address_new ( const pchar address,
puint16  port 
)

Creates new PSocketAddress.

Parameters
addressString representation of an address (i.e. "172.146.45.5").
portPort number.
Returns
Pointer to PSocketAddress in case of success, NULL otherwise.
Since
0.0.1
Note
It tries to automatically detect a socket family.

If the address is an IPv6 address, it can also contain a scope index separated from the address by the '' literal). Most target platforms should correctly parse such an address though some old operating systems may fail in case of lack of the getaddrinfo() call.

◆ p_socket_address_new_any()

P_LIB_API PSocketAddress* p_socket_address_new_any ( PSocketFamily  family,
puint16  port 
)

Creates new PSocketAddress for the any-address representation.

Parameters
familySocket family.
portPort number.
Returns
Pointer to PSocketAddress in case of success, NULL otherwise.
Since
0.0.1
Note
This call creates a network address for the set of all possible addresses, so you can't use it for receiving or sending data on a particular network address. If you need to bind a socket to the specific address (i.e. 127.0.0.1) use p_socket_address_new() instead.

◆ p_socket_address_new_from_native()

P_LIB_API PSocketAddress* p_socket_address_new_from_native ( pconstpointer  native,
psize  len 
)

Creates new PSocketAddress from the native socket address raw data.

Parameters
nativePointer to the native socket address raw data.
lenRaw data length, in bytes.
Returns
Pointer to PSocketAddress in case of success, NULL otherwise.
Since
0.0.1

◆ p_socket_address_new_loopback()

P_LIB_API PSocketAddress* p_socket_address_new_loopback ( PSocketFamily  family,
puint16  port 
)

Creates new PSocketAddress for the loopback interface.

Parameters
familySocket family.
portPort number.
Returns
Pointer to PSocketAddress in case of success, NULL otherwise.
Since
0.0.1
Note
This call creates a network address for the entire loopback network interface, so you can't use it for receiving or sending data on a particular network address. If you need to bind a socket to the specific address (i.e. 127.0.0.1) use p_socket_address_new() instead.

◆ p_socket_address_set_flow_info()

P_LIB_API void p_socket_address_set_flow_info ( PSocketAddress addr,
puint32  flowinfo 
)

Sets IPv6 traffic class and flow information.

Parameters
addrPSocketAddress to set flow information for.
flowinfoFlow information to set.
Since
0.0.1
Note
This call is valid only for an IPv6 address.
Some operating systems may not support this property.
See also
p_socket_address_is_flow_info_supported()

◆ p_socket_address_set_scope_id()

P_LIB_API void p_socket_address_set_scope_id ( PSocketAddress addr,
puint32  scope_id 
)

Sets an IPv6 set of interfaces for a scope.

Parameters
addrPSocketAddress to set the set of interfaces for.
scope_idIndex that identifies the set of interfaces for a scope.
Since
0.0.1
Note
This call is valid only for an IPv6 address.
Some operating systems may not support this property.
See also
p_socket_address_is_scope_id_supported()

◆ p_socket_address_to_native()

P_LIB_API pboolean p_socket_address_to_native ( const PSocketAddress addr,
ppointer  dest,
psize  destlen 
)

Converts PSocketAddress to the native socket address raw data.

Parameters
addrPSocketAddress to convert.
[out]destOutput buffer for raw data.
destlenLength in bytes of the dest buffer.
Returns
TRUE in case of success, FALSE otherwise.
Since
0.0.1