Draft: draft-ietf-taps-interface

Commentary: This is probably not done , but it 's getting closer to separating the abstract API from concrete API details . Edits , comments , and criticism are welcome , of course . 
 - we could do this , and take notes of the suggested changes ( which should be easy to apply ) in an issue - but then again , how is this more efficient than updating this PR ? 
 Add something about time durations to appendix ? In C++ it could be a time duration object , while in C it might be seconds . 
 lgtmWorks for me . Still , I think we should re - iterate the case of querying how to query selection results in a new PR .
Paragraph (version A):
The way these abstract concepts map into concrete implementations of
this API in a given language on a given platform largely depends on
the features of the language and the platform.  Actions could be
implemented as functions or method calls, for instance, and Events
could be implemented via event queues, handler functions or classes,
communicating sequential processes, or other asynchronous calling
conventions.
Paragraph (version A):
This specification treats Events and Errors similarly.  Errors, just
as any other Events, may occur asynchronously in network
applications.  However, it is recommended that implementations of
this interface also return Errors immediately, according to the error
handling idioms of the implementation platform, for errors that can
be immediately detected, such as inconsistency in Transport
Properties.  An error can provide an optional reason to the
application with further details about why the error occurred.
Paragraph (version B):
Boolean: Instances take the value "true" or "false".
Paragraph (version B):
Integer: Instances take positive or negative numeric integer
values, or sometimes special non-numeric (symbolic) values.
Paragraph (version B):
Numeric: Instances take positive or negative numeric values, or
sometimes special non-numeric (symbolic) values.
Paragraph (version B):
Enumeration: A family of types in which each instance takes one of
a fixed, predefined set of values specific to a given enumerated
type.
Paragraph (version B):
Tuple: An ordered grouping of multiple value types, represented as
a comma-separated list in parentheses, e.g., "(Enumeration,
Preference)".  Instances take a sequence of values each valid for
the corresponding value type.  The composition of types and their
order depends on the property and is fixed for the property.
Paragraph (version B):
Array: Denoted []Type, an instance takes a value for each of zero
or more elements in a sequence of the given Type.  An array may be
of fixed or variable length.
Paragraph (version B):
Collection: An unordered grouping of one or more values of the
same type.
Paragraph (version B):
For guidance on how these abstract concepts may be implemented in
languages in accordance with native design patterns and language and
platform features, see implmapping.
Paragraph (version A):
Boolean: can take the values "true" and "false"; representation is
implementation-dependent.
Paragraph (version A):
Integer: can take positive or negative numeric integer values;
range and representation is implementation-dependent.
Paragraph (version A):
Numeric: can take positive or negative numeric values; range and
representation is implementation-dependent.
Paragraph (version A):
Enumeration: can take one value of a finite set of values,
dependent on the property itself.  The representation is
implementation dependent.
Paragraph (version A):
Tuple: An ordered grouping of multiple value types.  In this this
document, it is written as a list in brackets, e.g.,
"(Enumeration, Preference)" The composition of types and their
order depends on the property and is fixed for the property.  The
actual representation is implementation-dependent.
Paragraph (version A):
Collection: An unordered grouping of one or more values of the
same type.  The actual representation, e.g. as a set or an array,
is implementation-dependent.
Paragraph (version A):
In addition, the pseudo-level "Default" can be used to reset the
property to the default level used by the implementation.  This level
will never show up when querying the value of a preference: the
effective preference must be returned instead.
Paragraph (version A):
Selection Properties of type "Preference" might often be frequently
used.  Implementations MAY therefore provide additional convenience
functions to simplify use, see preference-conv for examples.  In
addition, implementations MAY provide a mechanism to create
TransportProperties objects that are preconfigured for common use
cases as outlined in property-profiles.
Paragraph (version B):
Transport Properties for an established connection can be queried via
the Connection object, as outlined in introspection.
Paragraph (version B):
Representation of Security Parameters in implementations should
parallel that chosen for Transport Property names as recommended in
scope-of-interface-defn.
Paragraph (version A):
Whether the connection can be used to send data.  A connection can
not be used for sending if the connection was created with the
Selection Property "Direction of Communication" set to
"unidirectional receive" or if a Message marked as "Final" was
sent over this connection, see msg-final.
Paragraph (version A):
Whether the connection can be used to receive data.  A connection
cannot be used for reading if the connection was created with the
Selection Property "Direction of Communication" set to
"unidirectional send" or if a Message marked as "Final" was
received, see receiving-final-messages.  The latter is only
supported by certain transport protocols, e.g., by TCP as half-
closed connection.
Paragraph (version A):
For Connections that are Establishing: Transport Properties that
the application specified on the Preconnection, see selection-
props.
Paragraph (version B):
Whether the connection can be used to receive data.  A connection
cannot be used for reading if the connection was created with the
Selection Property "Direction of Communication" set to
"unidirectional send" or if a Message marked as "Final" was
received.  See receiving-final-messages.  The latter is only
supported by certain transport protocols, e.g., by TCP as half-
closed connection.
Paragraph (version B):
For Connections that are Established or Closing: Transport
Properties that the application specified on the Preconnection.
See selection-props.  Selection properties of type "Preference"
will be exposed as boolean values indicating whether or not the
property applies to the selected transport.
Paragraph (version B):
This property specifies how long to wait before deciding that an
active Connection has failed when trying to reliably deliver data to
the Remote Endpoint.  Adjusting this Property will only take effect
when the underlying stack supports reliability.  The special value
"Disabled" means that no timeout is scheduled.
Paragraph (version B):
A Transport Services system can request a protocol that supports
sending keep alive packets keep-alive.  This property specifies the
maximum length of time an idle connection (one for which no transport
packets have been sent) should wait before the Local Endpoint sends a
keep-alive packet to the Remote Endpoint.  Adjusting this Property
will only take effect when the underlying stack supports sending
keep-alive packets.  Guidance on setting this value for datagram
transports is provided in RFC8085.  A value greater than the
connection timeout (conn-timeout), or the special value "Disabled",
will disable the sending of keep-alive packets.