View Source quicer (quicer v0.0.303)
Summary
Functions
Accept new Connection (Server)
See also: accept/2.
Accept new stream on a existing connection with stream opts
Accept new stream on a existing connection with stream opts with timeout
Accept new stream on a existing connection with stream opts
close_connection/4
See also: async_close_connection/3.
close_stream/1
, prefer to use async_shutdown_stream/4See also: async_shutdown_stream/4, close_stream/4.
Initiate New Connection (Client)
{quic, connected, connection_handle()}
See also: handshake/2.
send/2
Caller should NOT expect to receive {quic, send_complete, Stream, send_complete_flag()}
note, check send_complete_flag() to ensure it is delivered or not.send/3
If QUICER_SEND_FLAG_SYNC is set , the caller should expect to receive {quic, send_complete, Stream, send_complete_flag()}
note, check send_complete_flag() to ensure it is delivered or not.shutdown_stream/2
See also: async_shutdown_stream/3.
shutdown_stream/4
Caller should expect to receive {quic, stream_closed, Stream, Flags}
See also: shutdown_connection/3.
See also: shutdown_connection/4.
Close library.
See also: close_stream/2.
See also: close_stream/4.
See also: close_stream/1, shutdown_stream/4.
Initiate New Connection (Client)
ssl:controlling_process/2
See also: wait_for_handoff/2.
ssl:getopts/2
ssl:getopt/2
ssl:getstat/2
{handoff_done, Stream, PostHandoff}
will be sent to the new owner. The new owner should block for this message before handle any stream data to ensure the ordering. 5. Revert stream active mode whatever handoff fail or success. also @see wait_for_handoff/2See also: accept/3, handshake/2.
See also: async_handshake/1, handshake/2.
Start listen on Port or "HOST:PORT".
Quicer library must be opened before any use.
ssl:peername/1
ssl:peername/1
Recv Data (Passive mode) Passive recv data from stream.
See also: reg_open/1.
GRegistraion should be opened before calling traffic APIs.
Registraion should be opened before calling traffic APIs. Registraion creates application context, worker threads shared for all the connections
Sending Unreliable Datagram
ssl:setopt/2
See also: shutdown_connection/4.
See also: shutdown_connection/4.
See also: shutdown_connection/1, shutdown_connection/2, shutdown_connection/3.
See also: shutdown_stream/1.
Shutdown stream gracefully, with app_errno 0
Start shutdown Stream process with flags and application specified error code.
ssl:sockname/1
Start new stream in connection, return new stream handle.
See also: controlling_process/2, handoff_stream/3.
Types
-type acceptor_opts() :: map().
-type alpn() :: string().
-type app_errno() :: non_neg_integer().
-type atom_reason() ::
success | pending | continue | out_of_memory | invalid_parameter | invalid_state |
not_supported | not_found | buffer_too_small | handshake_failure | aborted | address_in_use |
connection_timeout | connection_idle | internal_error | connection_refused | protocol_error |
ver_neg_error | unreachable | tls_error | user_canceled | alpn_neg_failure |
stream_limit_reached.
-type conf_handle() :: reference().
-type conn_opts() :: quic_settings() | #{alpn := [string()], conn_callback => module(), cert => filelib:filename(), certfile => filelib:filename(), key => filelib:filename(), keyfile => filelib:filename(), password => string(), verify => none | peer, handle => connection_handle(), nst => binary(), cacertfile => filelib:filename(), sslkeylogfile => filelib:filename(), peer_bidi_stream_count => uint16(), peer_unidi_stream_count => uint16(), handshake_idle_timeout_ms => non_neg_integer(), quic_event_mask => uint32(), param_conn_disable_1rtt_encryption => boolean(), param_conn_local_address => string()}.
-type conn_shutdown_flag() :: 0 | 1.
-type connection_handle() :: reference().
-type connection_opts() :: proplists:proplist() | quicer_connection:opts().
-type execution_profile() ::
quic_execution_profile_low_latency | quic_execution_profile_type_max_throughput |
quic_execution_profile_type_scavenger | quic_execution_profile_type_realtime.
-type fpbuffer() :: #{next_offset := non_neg_integer(), buffer := quic_data_buffer()}.
-type global_handle() :: quic_global.
-type handle() :: global_handle() | listener_handle() | connection_handle() | stream_handle() | conf_handle() | reg_handle().
-type ifrag() :: {Index :: non_neg_integer(), quic_data()}.
-type listen_on() :: inet:port_number() | string().
-type listen_opts() :: listen_security_opts() | quic_settings().
-type listen_security_opts() :: #{alpn := [alpn()], cert := file:filename(), certfile := file:filename(), key := file:filename(), keyfile := file:filename(), verify => none | peer | verify_peer | verify_none, cacertfile => filelib:filename(), password => string(), sslkeylogfile => filelib:filename(), allow_insecure => boolean(), quic_registration => reg_handle(), conn_acceptors => non_neg_integer()}.
-type listener_handle() :: reference().
-type listener_opts() :: proplists:proplist() | quicer_listener:listener_opts().
-type optlevel() :: false | quic_global | quic_registration | quic_configuration | quic_tls.
-type optname() :: optname_global() | optname_listener() | optname_conn() | optname_stream() | optname_reg() | optname_configuration() | optname_tls().
-type optname_configuration() :: param_configuration_settings | param_configuration_ticket_keys.
-type optname_conn() ::
param_conn_quic_version | param_conn_local_address | param_conn_remote_address |
param_conn_ideal_processor | param_conn_settings | param_conn_statistics |
param_conn_statistics_plat | param_conn_share_udp_binding |
param_conn_local_bidi_stream_count | param_conn_local_unidi_stream_count |
param_conn_max_stream_ids | param_conn_close_reason_phrase |
param_conn_stream_scheduling_scheme | param_conn_datagram_receive_enabled |
param_conn_datagram_send_enabled | param_conn_disable_1rtt_encryption |
param_conn_resumption_ticket | param_conn_peer_certificate_valid | param_conn_local_interface.
-type optname_global() ::
param_global_retry_memory_percent | param_global_supported_versions |
param_global_load_balacing_mode | param_global_perf_counters | param_global_settings |
param_global_version.
-type optname_listener() ::
param_listener_local_address | param_listener_stats | param_listener_cibir_id.
-type optname_reg() :: param_registration_cid_prefix.
-type optname_stream() ::
active | controlling_process | param_stream_id | param_stream_0rtt_length |
param_stream_ideal_send_buffer_size | param_stream_priority.
-type optname_tls() ::
param_tls_schannel_context_attribute_w | param_tls_handshake_info | param_tls_negotiated_alpn.
-type quic_data() :: #quic_data{}.
-type quic_data_buffer() :: ordsets:ordset(ifrag()).
-type quic_handle_level() :: quic_tls | quic_configuration | false.
-type quic_settings() :: #{max_bytes_per_key => uint64(), handshake_idle_timeout_ms => uint64(), idle_timeout_ms => uint64(), tls_client_max_send_buffer => uint32(), tls_server_max_send_buffer => uint32(), stream_recv_window_default => uint32(), stream_recv_buffer_default => uint32(), conn_flow_control_window => uint32(), max_stateless_operations => uint32(), initial_window_packets => uint32(), send_idle_timeout_ms => uint32(), initial_rtt_ms => uint32(), max_ack_delay_ms => uint32(), disconnect_timeout_ms => uint32(), keep_alive_interval_ms => uint32(), peer_bidi_stream_count => uint16(), peer_unidi_stream_count => uint16(), retry_memory_limit => uint16(), load_balancing_mode => uint16(), max_operations_per_drain => uint8(), send_buffering_enabled => uint8(), pacing_enabled => uint8(), migration_enabled => uint8(), datagram_receive_enabled => uint8(), server_resumption_level => uint8(), minimum_mtu => uint16(), maximum_mtu => uint16(), mtu_discovery_search_complete_timeout_us => uint64(), mtu_discovery_missing_probe_count => uint8(), max_binding_stateless_operations => uint16(), stateless_operation_expiration_ms => uint16()}.
-type recv_data_props() :: #{absolute_offset := integer(), len := integer(), flags := integer()}.
-type reg_handle() :: reference().
-type send_flags() :: non_neg_integer().
-type stream_handle() :: reference().
-type stream_open_flags() :: 0 | 1 | 2.
-type stream_opts() :: #{active := boolean() | once | integer(), open_flag => stream_open_flags(), start_flag => stream_start_flags(), event_mask => uint32(), disable_fpbuffer => boolean()}.
-type stream_shutdown_flags() :: 0 | 1 | 2 | 4 | 6 | 8.
-type stream_start_flags() :: 0 | 1 | 2 | 4 | 8.
-type uint8() :: 0..1 bsl 8 - 1.
-type uint16() :: 0..1 bsl 16 - 1.
-type uint32() :: 0..1 bsl 32 - 1.
-type uint64() :: 0..1 bsl 64 - 1.
-type user_opts() :: #{_ => _}.
Functions
-spec abi_version() -> quicer_nif:abi_version().
-spec accept(listener_handle(), acceptor_opts()) -> {ok, connection_handle()} | {error, any()}.
Accept new Connection (Server)
Accept new connection from listener_handle().
Calling process becomes the owner of the connection.-spec accept(listener_handle(), acceptor_opts(), timeout()) -> {ok, connection_handle()} | {error, badarg | param_error | not_enough_mem | badpid} | {error, timeout}.
See also: accept/2.
-spec accept_stream(connection_handle(), stream_opts()) -> {ok, stream_handle()} | {error, badarg | internal_error | bad_pid | owner_dead} | {erro, timeout}.
Accept new stream on a existing connection with stream opts
Calling process become the owner of the new stream and it get monitored by NIF.
Once the Calling process is dead, closing stream will be triggered. (@TODO may not be default)-spec accept_stream(connection_handle(), stream_opts(), timeout()) -> {ok, stream_handle()} | {error, badarg | internal_error | bad_pid | owner_dead} | {erro, timeout}.
Accept new stream on a existing connection with stream opts with timeout
Calling process become the owner of the new stream and it get monitored by NIF.
Once the Calling process is dead, closing stream will be triggered.See also: async_accept_stream/2.
-spec async_accept(listener_handle(), acceptor_opts()) -> {ok, listener_handle()} | {error, badarg | param_error | not_enough_mem | badpid}.
-spec async_accept_stream(connection_handle(), proplists:proplist() | map()) -> {ok, connection_handle()} | {error, any()}.
Accept new stream on a existing connection with stream opts
Calling process become the owner of the new stream and it get monitored by NIF.
Once the Calling process is dead, closing stream will be triggered.
Caller process should expect to receive {quic, new_stream, stream_handle(), new_stream_props()}
note, it returns
{ok, connection_handle()}.
NOT {ok, stream_handle()}.
See also: async_accept_stream/2.
-spec async_close_connection(connection_handle()) -> ok.
-spec async_close_connection(connection_handle(), conn_shutdown_flag(), app_errno()) -> ok.
close_connection/4
See also: async_close_connection/3.
-spec async_close_stream(stream_handle()) -> ok | {error, badarg}.
close_stream/1
, prefer to use async_shutdown_stream/4See also: async_shutdown_stream/4, close_stream/4.
-spec async_connect(inet:hostname() | inet:ip_address(), inet:port_number(), conn_opts()) -> {ok, connection_handle()} | {error, conn_open_error | config_error | conn_start_error}.
Initiate New Connection (Client)
Async variant of connect/4See also: connect/4.
-spec async_csend(connection_handle(), iodata(), stream_opts(), send_flags()) -> {ok, stream_handle()} | {error, any()} | {error, stm_open_error, atom_reason()} | {error, stream_send_error, atom_reason()}.
-spec async_handshake(connection_handle()) -> ok | {error, any()}.
{quic, connected, connection_handle()}
See also: handshake/2.
-spec async_send(stream_handle(), iodata()) -> {ok, BytesSent :: pos_integer()} | {error, badarg | not_enough_mem | closed} | {error, stream_send_error, atom_reason()}.
send/2
Caller should NOT expect to receive {quic, send_complete, Stream, send_complete_flag()}
note, check send_complete_flag() to ensure it is delivered or not.
-spec async_send(stream_handle(), iodata(), non_neg_integer()) -> {ok, BytesSent :: pos_integer()} | {error, badarg | not_enough_mem | closed} | {error, stream_send_error, atom_reason()}.
send/3
If QUICER_SEND_FLAG_SYNC is set , the caller should expect to receive {quic, send_complete, Stream, send_complete_flag()}
note, check send_complete_flag() to ensure it is delivered or not.
-spec async_shutdown_connection(connection_handle(), conn_shutdown_flag(), app_errno()) -> ok | {error, badarg | closed}.
-spec async_shutdown_stream(stream_handle()) -> ok | {error, badarg | atom_reason()}.
shutdown_stream/2
See also: async_shutdown_stream/3.
-spec async_shutdown_stream(stream_handle(), stream_shutdown_flags(), app_errno()) -> ok | {error, badarg}.
shutdown_stream/4
Caller should expect to receive {quic, stream_closed, Stream, Flags}
-spec close_connection(connection_handle()) -> ok | {error, badarg}.
-spec close_connection(connection_handle(), conn_shutdown_flag(), app_errno()) -> ok | {error, badarg | timeout}.
See also: shutdown_connection/3.
-spec close_connection(connection_handle(), conn_shutdown_flag(), app_errno(), timeout()) -> ok | {error, badarg | timeout}.
See also: shutdown_connection/4.
-spec close_lib() -> ok.
Close library.
This is reserved for upgrade support
Danger! Do not use it!-spec close_listener(listener_handle()) -> ok | {error, badarg | closed | timeout}.
-spec close_listener(listener_handle(), timer:time()) -> ok | {error, badarg | closed | timeout}.
-spec close_registration(Handle) -> quicer_nif:close_registration(Handle).
-spec close_stream(stream_handle()) -> ok | {error, badarg | timeout}.
See also: close_stream/2.
-spec close_stream(stream_handle(), timeout()) -> ok | {error, badarg | timeout}.
See also: close_stream/4.
-spec close_stream(stream_handle(), stream_shutdown_flags(), app_errno(), timeout()) -> ok | {error, badarg | timeout}.
See also: close_stream/1, shutdown_stream/4.
-spec connect(inet:hostname() | inet:ip_address(), inet:port_number(), conn_opts(), timeout()) -> {ok, connection_handle()} | {error, conn_open_error | config_error | conn_start_error} | {error, timeout} | {error, nst_not_found}.
Initiate New Connection (Client)
Initiate new connection to remote endpoint with connection opts specified.See also: async_connect/3.
-spec controlling_process(connection_handle() | stream_handle(), pid()) -> ok | {error, closed | badarg | owner_dead | not_owner}.
ssl:controlling_process/2
See also: wait_for_handoff/2.
-spec defrag_fpbuffer(Offset :: non_neg_integer(), quic_data_buffer()) -> {NewOffset :: non_neg_integer(), NewBuffer :: quic_data_buffer(), Res :: [quic_data()]}.
-spec get_conn_owner(C) -> quicer_nif:get_conn_owner(C).
-spec get_conn_rid(connection_handle()) -> {ok, non_neg_integer()} | {error, any()}.
-spec get_connections() -> quicer_nif:get_connections().
-spec get_connections(Reg | global) -> quicer_nif:get_connections(Reg).
-spec get_listener_owner(L) -> quicer_nif:get_listener_owner(L).
-spec get_listeners() -> quicer_nif:get_listeners().
-spec get_listeners(Reg | global) -> quicer_nif:get_listeners(Reg).
-spec get_registration_name(Handle) -> quicer_nif:get_registration_name(Handle).
-spec get_stream_id(Stream :: stream_handle()) -> {ok, integer()} | {error, any()} | not_found.
-spec get_stream_owner(S) -> quicer_nif:get_stream_owner(S).
-spec get_stream_rid(stream_handle()) -> {ok, non_neg_integer()} | {error, any()}.
ssl:getopts/2
-spec getopt(handle(), optname(), optlevel()) -> not_found | {ok, [any()]} | {error, badarg | param_error | internal_error | not_enough_mem} | {error, atom_reason()}.
ssl:getopt/2
-spec getstat(connection_handle(), [inet:stat_option()]) -> {ok, list()} | {error, any()}.
ssl:getstat/2
-spec handoff_stream(stream_handle(), pid()) -> ok | {error, any()}.
-spec handoff_stream(stream_handle(), pid(), term()) -> ok | {error, any()}.
{handoff_done, Stream, PostHandoff}
will be sent to the new owner. The new owner should block for this message before handle any stream data to ensure the ordering. 5. Revert stream active mode whatever handoff fail or success. also @see wait_for_handoff/2
-spec handshake(connection_handle()) -> {ok, connection_handle()} | {error, any()}.
See also: accept/3, handshake/2.
-spec handshake(connection_handle(), timeout()) -> {ok, connection_handle()} | {error, any()}.
See also: async_handshake/1, handshake/2.
-spec is_unidirectional(stream_open_flags()) -> boolean().
-spec listen(listen_on(), listen_opts()) -> {ok, listener_handle()} | {error, quic_tls} | {error, cacertfile} | {error, quic_registration} | {error, badarg} | {error, listener_open_error, atom_reason()} | {error, listener_start_error, atom_reason()}.
Start listen on Port or "HOST:PORT".
listener_handle() is used for accepting new connection. notes,
1. Port binding is done in NIF context, thus you cannot see it from inet:i().
2. ListenOn can either be integer() for Port or be String for HOST:PORT
3. There is no address binding even HOST is specified.-spec listener(quicer_listener:listener_name() | {quicer_listener:listener_name(), quicer_listener:listen_on()}) -> {ok, pid()} | {error, not_found}.
-spec listeners() -> [{{quicer_listener:listener_name(), quicer_listener:listen_on()}, pid()}].
-spec merge_quic_datalist([quic_data()]) -> {iolist(), Size :: non_neg_integer(), Flag :: integer()}.
-spec negotiated_protocol(Conn :: connection_handle()) -> {ok, Protocol :: binary()} | {error, Reason :: any()}.
-spec new_fpbuffer() -> fpbuffer().
-spec new_registration(Name, Profile) -> quicer_nif:new_registration(Name, Profile).
-spec open_connection() -> {ok, connection_handle()} | {error, atom_reason()}.
-spec open_lib() -> {ok, true} | {ok, false} | {ok, debug} | {error, open_failed, atom_reason()}.
Quicer library must be opened before any use.
This is called automatically while quicer application is started-spec peercert(connection_handle() | stream_handle()) -> {ok, Cert :: public_key:der_encoded()} | {error, any()}.
ssl:peername/1
-spec peername(connection_handle() | stream_handle()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, any()}.
ssl:peername/1
-spec perf_counters() -> {ok, [{atom(), integer()}]} | {error, any()}.
-spec quic_data({quic, binary(), stream_handle(), recv_data_props()}) -> quic_data().
-spec recv(stream_handle(), Count :: non_neg_integer()) -> {ok, binary()} | {error, any()}.
Recv Data (Passive mode) Passive recv data from stream.
If Len = 0, return all data in recv buffer if it is not empty. if buffer is empty, blocking for a Quic msg from stack to arrive and return all data in that msg.
If Len > 0, desired bytes will be returned, other data would be left in recv buffer.
Suggested to use Len=0 if caller want to buffer or reassemble the data on its own.
note, the requested Len cannot exceed the 'stream_recv_window_default' specified in connection opts otherwise the function will never return-spec reg_close() -> ok.
See also: reg_open/1.
GRegistraion should be opened before calling traffic APIs.
This is called automatically when quicer application starts with app env:profile
See also: reg_close/0, reg_open/1.
-spec reg_open(execution_profile()) -> ok | {error, badarg}.
Registraion should be opened before calling traffic APIs. Registraion creates application context, worker threads shared for all the connections
Currently only support one application.See also: reg_close/0, reg_open/1.
-spec send(stream_handle(), iodata()) -> {ok, BytesSent :: pos_integer()} | {error, cancelled} | {error, badarg | not_enough_mem | closed} | {error, stream_send_error, atom_reason()}.
-spec send(stream_handle(), iodata(), non_neg_integer()) -> {ok, BytesSent :: pos_integer()} | {error, cancelled} | {error, badarg | not_enough_mem | closed} | {error, stream_send_error, atom_reason()}.
-spec send_dgram(connection_handle(), binary()) -> {ok, BytesSent :: pos_integer()} | {error, badarg | not_enough_mem | closed} | {error, dgram_send_error, atom_reason()}.
Sending Unreliable Datagram
ref: https://datatracker.ietf.org/doc/html/draft-ietf-quic-datagramSee also: send/2.
-spec setopt(handle(), optname(), any()) -> ok | {error, badarg | param_error | internal_error | not_enough_mem} | {error, atom_reason()}.
ssl:setopt/2
-spec setopt(handle(), optname(), any(), quic_handle_level()) -> ok | {error, badarg | param_error | internal_error | not_enough_mem} | {error, atom_reason()}.
-spec shutdown_connection(connection_handle()) -> ok | {error, timeout | closed}.
See also: shutdown_connection/4.
-spec shutdown_connection(connection_handle(), timeout()) -> ok | {error, timeout | badarg}.
See also: shutdown_connection/4.
-spec shutdown_connection(connection_handle(), conn_shutdown_flag(), app_errno()) -> ok | {error, timeout | badarg}.
-spec shutdown_connection(connection_handle(), conn_shutdown_flag(), app_errno(), timeout()) -> ok | {error, timeout | badarg}.
See also: shutdown_connection/1, shutdown_connection/2, shutdown_connection/3.
-spec shutdown_registration(Handle) -> quicer_nif:shutdown_registration(Handle).
-spec shutdown_registration(Handle, IsSilent, ErrCode) ->
quicer_nif:shutdown_registration(Handle, IsSilent, ErrCode).
-spec shutdown_stream(stream_handle()) -> ok | {error, badarg}.
See also: shutdown_stream/1.
-spec shutdown_stream(stream_handle(), timeout()) -> ok | {error, badarg} | {error, timeout}.
Shutdown stream gracefully, with app_errno 0
returns when both endpoints closed the streamSee also: shutdown_stream/4.
-spec shutdown_stream(stream_handle(), stream_shutdown_flags(), app_errno(), timeout()) -> ok | {error, badarg} | {error, timeout}.
Start shutdown Stream process with flags and application specified error code.
returns when stream closing is confirmed in the stack (Blocking).
Flags could be used to control the behavior like half-close.See also: async_shutdown_stream/4.
-spec sockname(listener_handle() | connection_handle() | stream_handle()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, any()}.
ssl:sockname/1
-spec spawn_listener(Appname :: atom() | listener_handle(), listen_on(), {listener_opts(), connection_opts(), stream_opts() | user_opts()}) -> {ok, pid()} | {error, any()}.
-spec start_listener(listener_handle(), listen_on(), listen_opts()) -> {ok, pid()} | {error, any()}.
-spec start_stream(connection_handle(), stream_opts()) -> {ok, stream_handle()} | {error, badarg | internal_error | bad_pid | owner_dead} | {error, stream_open_error, atom_reason()} | {error, stream_start_error, atom_reason()}.
Start new stream in connection, return new stream handle.
Calling process becomes the owner of the stream.
Both client and server could start the stream.-spec stop_listener(listener_handle()) -> ok.
-spec terminate_listener(atom() | listener_handle()) -> ok.
-spec wait_for_handoff(From :: pid(), stream_handle()) -> {error, owner_down} | {ok, PostInfo :: term()}.
See also: controlling_process/2, handoff_stream/3.