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: not abstract enough. Functions/properties like getnameinfo/addr/port do not work for e.g. sockaddr_un

    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

    """

    52

        A socket-level endpoint address, which contains the full socket parameters and an bind/connect address.

    53

    54

        A full addrinfo struct is stored, but ai_canonname and ai_addr are stored as (optional) objects outside of the

    55

        addrinfo struct.

    58

        >>> ai = addrinfo()

    59

        >>> ai.addr

    60

        >>> ai.canonname

    62

        family=0, socktype=0, protocol=0, addr=0.0.0.0:0, canonname=None

    63

    """

    64

    65

    # canonname is not stored

    66

    # may be NULL

    67

    cdef platform.addrinfo ai

    68

    69

    # may be NULL

    70

    cdef sockaddr ai_addr

    71

    cdef object ai_canonname

    72

    73

    # update self.ai.ai_* to reflect self.ai_*

    74

    cdef _init_ai_members (self)

    75

    76

    # set the contents of self.ai from the given real addrinfo

    77

    # this ignores the ai_canonname attribute

    78

    cdef _init_addrinfo (self, platform.addrinfo *ai)

    79

    80

# build and return a new addrinfo instance

    81

cdef addrinfo build_addrinfo (platform.addrinfo *c_ai)

    82

    83

cdef class endpoint :

    84

    """

    85

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

    86

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

    87

    88

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

    89

        using getaddrinfo.

    90

    91

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

    92

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

    93

        >>> str(e)

    94

        'hostname=127.0.0.1, service=80'

    95

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

    96

        >>> len(res)

    97

        1

    98

        >>> str(res[0])

    99

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

   100

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

   101

        >>> str(e)

   102

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

   103

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

   104

        >>> len(res)

   105

        1

   106

        >>> str(res[0])

   107

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

   108

   109

    """

   110

   111

    # our defining attributes, set via __init__

   113

   114

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

   115