xref: /qemu/qapi/sockets.json (revision 7c1f51bf) 
1# -*- Mode: Python -*-
2# vim: filetype=python
3
4##
5# = Socket data types
6##
7
8{ 'include': 'common.json' }
9
10##
11# @NetworkAddressFamily:
12#
13# The network address family
14#
15# @ipv4: IPV4 family
16#
17# @ipv6: IPV6 family
18#
19# @unix: unix socket
20#
21# @vsock: vsock family (since 2.8)
22#
23# @unknown: otherwise
24#
25# Since: 2.1
26##
27{ 'enum': 'NetworkAddressFamily',
28  'data': [ 'ipv4', 'ipv6', 'unix', 'vsock', 'unknown' ] }
29
30##
31# @InetSocketAddressBase:
32#
33# @host: host part of the address
34# @port: port part of the address
35##
36{ 'struct': 'InetSocketAddressBase',
37  'data': {
38    'host': 'str',
39    'port': 'str' } }
40
41##
42# @InetSocketAddress:
43#
44# Captures a socket address or address range in the Internet
45# namespace.
46#
47# @numeric: true if the host/port are guaranteed to be numeric, false
48#     if name resolution should be attempted.  Defaults to false.
49#     (Since 2.9)
50#
51# @to: If present, this is range of possible addresses, with port
52#     between @port and @to.
53#
54# @ipv4: whether to accept IPv4 addresses, default try both IPv4 and
55#     IPv6
56#
57# @ipv6: whether to accept IPv6 addresses, default try both IPv4 and
58#     IPv6
59#
60# @keep-alive: enable keep-alive when connecting to this socket.  Not
61#     supported for passive sockets.  (Since 4.2)
62#
63# @mptcp: enable multi-path TCP. (Since 6.1)
64#
65# Since: 1.3
66##
67{ 'struct': 'InetSocketAddress',
68  'base': 'InetSocketAddressBase',
69  'data': {
70    '*numeric':  'bool',
71    '*to': 'uint16',
72    '*ipv4': 'bool',
73    '*ipv6': 'bool',
74    '*keep-alive': 'bool',
75    '*mptcp': { 'type': 'bool', 'if': 'HAVE_IPPROTO_MPTCP' } } }
76
77##
78# @UnixSocketAddress:
79#
80# Captures a socket address in the local ("Unix socket") namespace.
81#
82# @path: filesystem path to use
83#
84# @abstract: if true, this is a Linux abstract socket address.  @path
85#     will be prefixed by a null byte, and optionally padded with null
86#     bytes.  Defaults to false.  (Since 5.1)
87#
88# @tight: if false, pad an abstract socket address with enough null
89#     bytes to make it fill struct sockaddr_un member sun_path.
90#     Defaults to true.  (Since 5.1)
91#
92# Since: 1.3
93##
94{ 'struct': 'UnixSocketAddress',
95  'data': {
96    'path': 'str',
97    '*abstract': { 'type': 'bool', 'if': 'CONFIG_LINUX' },
98    '*tight': { 'type': 'bool', 'if': 'CONFIG_LINUX' } } }
99
100##
101# @VsockSocketAddress:
102#
103# Captures a socket address in the vsock namespace.
104#
105# @cid: unique host identifier
106#
107# @port: port
108#
109# Note: string types are used to allow for possible future hostname or
110#     service resolution support.
111#
112# Since: 2.8
113##
114{ 'struct': 'VsockSocketAddress',
115  'data': {
116    'cid': 'str',
117    'port': 'str' } }
118
119##
120# @InetSocketAddressWrapper:
121#
122# Since: 1.3
123##
124{ 'struct': 'InetSocketAddressWrapper',
125  'data': { 'data': 'InetSocketAddress' } }
126
127##
128# @UnixSocketAddressWrapper:
129#
130# Since: 1.3
131##
132{ 'struct': 'UnixSocketAddressWrapper',
133  'data': { 'data': 'UnixSocketAddress' } }
134
135##
136# @VsockSocketAddressWrapper:
137#
138# Since: 2.8
139##
140{ 'struct': 'VsockSocketAddressWrapper',
141  'data': { 'data': 'VsockSocketAddress' } }
142
143##
144# @StringWrapper:
145#
146# Since: 1.3
147##
148{ 'struct': 'StringWrapper',
149  'data': { 'data': 'String' } }
150
151##
152# @SocketAddressLegacy:
153#
154# Captures the address of a socket, which could also be a named file
155# descriptor
156#
157# Note: This type is deprecated in favor of SocketAddress.  The
158#     difference between SocketAddressLegacy and SocketAddress is that
159#     the latter has fewer {} on the wire.
160#
161# Since: 1.3
162##
163{ 'union': 'SocketAddressLegacy',
164  'base': { 'type': 'SocketAddressType' },
165  'discriminator': 'type',
166  'data': {
167    'inet': 'InetSocketAddressWrapper',
168    'unix': 'UnixSocketAddressWrapper',
169    'vsock': 'VsockSocketAddressWrapper',
170    'fd': 'StringWrapper' } }
171
172##
173# @SocketAddressType:
174#
175# Available SocketAddress types
176#
177# @inet: Internet address
178#
179# @unix: Unix domain socket
180#
181# @vsock: VMCI address
182#
183# @fd: decimal is for file descriptor number, otherwise a file
184#     descriptor name.  Named file descriptors are permitted in
185#     monitor commands, in combination with the 'getfd' command.
186#     Decimal file descriptors are permitted at startup or other
187#     contexts where no monitor context is active.
188#
189# Since: 2.9
190##
191{ 'enum': 'SocketAddressType',
192  'data': [ 'inet', 'unix', 'vsock', 'fd' ] }
193
194##
195# @SocketAddress:
196#
197# Captures the address of a socket, which could also be a named file
198# descriptor
199#
200# @type: Transport type
201#
202# Since: 2.9
203##
204{ 'union': 'SocketAddress',
205  'base': { 'type': 'SocketAddressType' },
206  'discriminator': 'type',
207  'data': { 'inet': 'InetSocketAddress',
208            'unix': 'UnixSocketAddress',
209            'vsock': 'VsockSocketAddress',
210            'fd': 'String' } }
211