1

"""

     2

    Socket addresses at various levels:

     3

     4

        sockaddr    - specific network-level address for socket operations

     5

        addrinfo    - information on a specific sockaddr including its socket parameters

     6

        endpoint    - human-readable network address, corresponding to multiple sockaddr's

     7

"""

     8

     9

cimport qmsk.net.libc as libc

    10

    11

cimport qmsk.net.socket.platform as platform

    12

    13

cdef class sockaddr :

    14

    """

    15

        A network-level socket address

    16

    17

        XXX: rename to 'address'

    18

    19

        >>> sockaddr().family

    20

        0

    21

        >>> sockaddr().port

    22

        Traceback (most recent call last):

    23

          ...

    24

        NotImplementedError

    25

        >>> sockaddr().getnameinfo()

    26

        Traceback (most recent call last):

    27

          ...

    28

        NotImplementedError

    29

    """

    30

    31

    # address family

    32

    # XXX: this should be a class constant! It's part of our type safety!

    33

    cdef readonly platform.sa_family_t family

    34

    35

    cdef void _init_family (self, platform.sa_family_t family = ?)

    36

    37

    # get the sockaddr/socklen

    38

    # each of these can be NULL to ignore it

    39

    cdef int _get_sockaddr (self, platform.sockaddr **sa_ptr, platform.socklen_t *sa_len) except -1

    40

    41

    cdef platform.sockaddr* _get_sockaddr_ptr (self) except NULL

    42

    cdef platform.socklen_t _get_sockaddr_len (self) except -1

    43

    44

    # set the sockaddr, socklen must match

    45

    cdef int _set_sockaddr (self, platform.sockaddr *sa, size_t sa_len) except -1

    46

    47

# build a sockaddr from the given sockaddr struct, based on sa_family

    48

cdef sockaddr build_sockaddr (platform.sockaddr *sa, size_t sa_len)

    49

    50

cdef class addrinfo :

    51

    """

    56

    67

    78

    79

# build and return a new addrinfo instance

    80

cdef addrinfo build_addrinfo (platform.addrinfo *c_ai)

    81

    82

cdef class endpoint :

    83

    """

    84

        A network-level socket endpoint. This is the level that humans mostly work with, but the tricky bit is that

    85

        an endpoint can map to more than one sockaddr...

    86

    87

        Hence, endpoints are stored as human-readable hostname/service strings, which are then translated to sockaddrs

    88

        using getaddrinfo.

    89

    90

        >>> from __future__ import absolute_import; import socket as _socket

    91

        >>> e = endpoint('127.0.0.1', 80)

    92

        >>> str(e)

    93

        'hostname=127.0.0.1, service=80'

    94

        >>> res = e.getaddrinfo(_socket.AF_UNSPEC, _socket.SOCK_STREAM)

    95

        >>> len(res)

    96

        1

    97

        >>> str(res[0])

    98

        'family=2, socktype=1, protocol=6, addr=127.0.0.1:80, canonname=None'

    99

        >>> e = endpoint('2001::5', 80)

   100

        >>> str(e)

   101

        'hostname=2001::5, service=80'

   102

        >>> res = e.getaddrinfo(_socket.AF_UNSPEC, _socket.SOCK_STREAM)

   103

        >>> len(res)

   104

        1

   105

        >>> str(res[0])

   106

        'family=10, socktype=1, protocol=6, addr=[2001::5]:80, canonname=None'

   107

   108

    """

   109

   110

    # our defining attributes, set via __init__

   111

    cdef object hostname, service

   112

   113

    cpdef getaddrinfo (self, int family, int socktype, int protocol = ?, int flags = ?)

   114