One document matched: draft-irtf-samrg-common-api-09.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="exp" docName="draft-irtf-samrg-common-api-09" ipr="trust200902">
<front>
<title abbrev="Common Mcast API">A Common API for Transparent Hybrid
Multicast</title>
<author fullname="Matthias Waehlisch" initials="M." surname="Waehlisch">
<organization>link-lab & FU Berlin</organization>
<address>
<postal>
<street>Hoenower Str. 35</street>
<city>Berlin</city>
<code>10318</code>
<country>Germany</country>
</postal>
<email>mw@link-lab.net</email>
<uri>http://www.inf.fu-berlin.de/~waehl</uri>
</address>
</author>
<author fullname="Thomas C. Schmidt" initials="T C." surname="Schmidt">
<organization>HAW Hamburg</organization>
<address>
<postal>
<street>Berliner Tor 7</street>
<city>Hamburg</city>
<code>20099</code>
<country>Germany</country>
</postal>
<email>schmidt@informatik.haw-hamburg.de</email>
<uri>http://inet.cpt.haw-hamburg.de/members/schmidt</uri>
</address>
</author>
<author fullname="Stig Venaas" initials="S." surname="Venaas">
<organization>cisco Systems</organization>
<address>
<postal>
<street>Tasman Drive</street>
<city>San Jose</city>
<region>CA</region>
<code>95134</code>
<country>USA</country>
</postal>
<email>stig@cisco.com</email>
</address>
</author>
<date />
<workgroup>SAM Research Group</workgroup>
<abstract>
<t>Group communication services exist in a large variety of flavors and
technical implementations at different protocol layers. Multicast data
distribution is most efficiently performed on the lowest available
layer, but a heterogeneous deployment status of multicast technologies
throughout the Internet requires an adaptive service binding at runtime.
Today, it is difficult to write an application that runs everywhere and
at the same time makes use of the most efficient multicast service
available in the network. Facing robustness requirements, developers are
frequently forced to use a stable, upper layer protocol provided by the
application itself. This document describes a common multicast API that
is suitable for transparent communication in underlay and overlay, and
grants access to the different multicast flavors. It proposes an
abstract naming by multicast URIs and discusses mapping mechanisms
between different namespaces and distribution technologies.
Additionally, this document describes the application of this API for
building gateways that interconnect current multicast domains throughout
the Internet. It reports on an implementation of the programming
interface, including a service middleware. This document is a product of
the Scalable Adaptive Multicast (SAM) Research Group.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>Currently, group application programmers need to make the choice of
the distribution technology that the application will require at
runtime. There is no common communication interface that abstracts
multicast transmission and subscriptions from the deployment state at
runtime, nor has been the use of DNS for group addresses established.
The standard multicast socket options <xref target="RFC3493"></xref>
<xref target="RFC3678"></xref> are bound to an IP version by not
distinguishing between naming and addressing of multicast identifiers.
Group communication, however, is commonly implemented in different
flavors such as any source (ASM) vs. source specific multicast (SSM), on
different layers (e.g., IP vs. application layer multicast), and may be
based on different technologies on the same tier as with IPv4 vs. IPv6.
The objective of this document is to provide for programmers a universal
access to group services.</t>
<t>Multicast application development should be decoupled of
technological deployment throughout the infrastructure. It requires a
common multicast API that offers calls to transmit and receive multicast
data independent of the supporting layer and the underlying
technological details. For inter-technology transmissions, a consistent
view on multicast states is needed as well. This document describes an
abstract group communication API and core functions necessary for
transparent operations. Specific implementation guidelines with respect
to operating systems or programming languages are out of scope of this
document.</t>
<t>In contrast to the standard multicast socket interface, the API
introduced in this document abstracts naming from addressing. Using a
multicast address in the current socket API predefines the corresponding
routing layer. In this specification, the multicast name used for
joining a group denotes an application layer data stream that is
identified by a multicast URI, independent of its binding to a specific
distribution technology. Such a group name can be mapped to variable
routing identifiers.</t>
<t>The aim of this common API is twofold: <list style="symbols">
<t>Enable any application programmer to implement group-oriented
data communication independent of the underlying delivery
mechanisms. In particular, allow for a late binding of group
applications to multicast technologies that makes applications
efficient, but robust with respect to deployment aspects.</t>
<t>Allow for a flexible namespace support in group addressing and
thereby separate naming and addressing resp. routing schemes from
the application design. This abstraction does not only decouple
programs from specific aspects of underlying protocols, but it may
open application design to extend to specifically flavored group
services.</t>
</list></t>
<t>Multicast technologies may be of various peer-to-peer kinds, IPv4 or
IPv6 network layer multicast, or implemented by some other application
service. Corresponding namespaces may be IP addresses or DNS naming,
overlay hashes, or other application layer group identifiers like
<sip:*@peanuts.org>, but they can also be names independently
defined by the applications. Common namespaces are introduced later in
this document but follow an open concept suitable for further
extensions.</t>
<t>This document also discusses mapping mechanisms between different
namespaces and forwarding technologies and proposes expressions of
defaults for an intended binding. Additionally, the multicast API
provides internal interfaces to access current multicast states at the
host. Multiple multicast protocols may run in parallel on a single host.
These protocols may interact to provide a gateway function that bridges
data between different domains. The usage of this API at gateways
operating between current multicast instances throughout the Internet is
described as well. Finally, a report on an implementation of the
programming interface, including a service middleware, is presented.</t>
<t>This document represents the consensus of the SAM Research Group. It
has been reviewed by the Research Group members active in the specific
area of work. In addition, this document has been comprehensively
reviewed by people who are not "in" the Research Group but are experts
in the area.</t>
<section title="Use Cases for the Common API">
<t>The following generic use cases can be identified that require an
abstract common API for multicast services:</t>
<t><list style="hanging">
<t
hangText="Application Programming Independent of Technologies:">Application
programmers are provided with group primitives that remain
independent of multicast technologies and their deployment in
target domains. They are thus enabled to develop programs once
that run in every deployment scenario. The use of Group Names in
the form of abstract meta data types allows applications to remain
namespace-agnostic in the sense that the resolution of namespaces
and name-to-address mappings may be delegated to a system service
at runtime. Thereby, the complexity is minimized as developers
need not care about how data is distributed in groups, while
system service can take advantage of extended information of the
network environment as acquired at startup.</t>
<t hangText="Global Identification of Groups:">Groups can be
identified independent of technological instantiations and beyond
deployment domains. Taking advantage of the abstract naming, an
application is thus enabled to match data received from different
Interface technologies (e.g., IPv4, IPv6, and overlays) to belong
to the same group. This not only increases flexibility - an
application may for instance combine heterogeneous multipath
streams - but also simplifies the design and implementation of
gateways.</t>
<t hangText="Uniform Access to Multicast Flavors:">The URI naming
scheme uniformly supports different flavors of group communication
such as any source and source specific multicast, and selective
broadcast, independent of their service instantiation. The
traditional SSM model, for instance, can experience manifold
support, either by directly mapping the multicast URI (i.e.,
"group@instantiation") to an (S,G) state on the IP layer, or by
first resolving S for a subsequent group address query, or by
transferring this process to any of the various source specific
overlay schemes, or by delegating to a plain replication server.
The application programmer can invoke any of these underlying
mechanisms with the same line of code.</t>
<t
hangText="Simplified Service Deployment through Generic Gateways:">The
common multicast API allows for an implementation of abstract
gateway functions with mappings to specific technologies residing
at a system level. Generic gateways may provide a simple bridging
service and facilitate an inter-domain deployment of
multicast.</t>
<t hangText="Mobility-agnostic Group Communication:">Group naming
and management as foreseen in the common multicast API remain
independent of locators. Naturally, applications stay unaware of
any mobility-related address changes. Handover-initiated
re-addressing is delegated to the mapping services at the system
level and may be designed to smoothly interact with mobility
management solutions provided at the network or transport layer
(see <xref target="RFC5757"></xref> for mobility-related
aspects).</t>
</list></t>
</section>
<section title="Illustrative Examples">
<section title="Support of Multiple Underlying Technologies">
<t>On a very high-level, the common multicast API provides the
application programmer with one single interface to manage multicast
content independent of the technology underneath. Considering the
following simple example in <xref target="fig:example"></xref>, a
multicast source S is connected via IPv4 and IPv6. It distributes
one flow of multicast content (e.g., a movie). Receivers are
connected via IPv4/v6 and overlay multicast, respectively.</t>
<figure anchor="fig:example"
title="Common scenario: Source S sends the same multicast content via different technologies">
<artwork><![CDATA[ +-------+ +-------+ +-------+
| S | | R1 | | R3 |
+-------+ +-------+ +-------+
v6| v4| |v4 |OLM
| | / |
| ***| *** ***/ ** *** /*** *** ***
\* |* ** /** * * /* ** ** *
*\ \_______/_______*__v4__+-------+ * / *
*\ IPv4/v6 * | R2 |__OLM__ *_/ Overlay Mcast *
* \_________________*__v6__+-------+ * *
* ** ** ** * * ** ** ** *
*** *** *** *** *** *** *** ***
]]></artwork>
</figure>
<t>Using the current BSD socket API, the application programmer
needs to decide on the IP technologies at coding time. Additional
distribution techniques, such as overlay multicast, must be
individually integrated into the application. For each technology,
the application programmer needs to create a separate socket and
initiate a dedicated join or send. As the current socket API does
not distinguish between group name and group address, the content
will be delivered multiple times to the same receiver (cf., R2).
Whenever the source distributes content via a technology that is not
supported by the receivers or its Internet Service Provider (cf.,
R3), a gateway is required. Gateway functions rely on a coherent
view of the multicast group states.</t>
<t>The common multicast API simplifies programming of multicast
applications as it abstracts content distribution from specific
technologies. In addition to calls that implement receiving and
sending of multicast data, the API provides service calls to grant
access to internal multicast states at the host. The API description
in this document defines a minimal set of programming interfaces to
the system components at the host to operate group communication. It
is left to specific implementations to provide additional
convenience functions for programmers.</t>
<t>The implementation of content distribution for the example shown
in <xref target="fig:example"></xref> may then look like:</t>
<t></t>
<figure title="Send/receive example using the common multicast API">
<artwork><![CDATA[ //Initialize multicast socket
MulticastSocket m = new MulticastSocket();
//Associate all available interfaces
m.addInterface(getInterfaces());
//Subscribe to multicast group
m.join(URI("ham:opaque:news@cnn.com"));
//Send to multicast group
m.send(URI("ham:opaque:news@cnn.com"),message);
]]></artwork>
</figure>
<t></t>
<t>The gateway function for R2 can be implemented by service calls
that look like:</t>
<t></t>
<figure title="Gateway example using the common multicast API">
<artwork><![CDATA[ //Initialize multicast socket
MulticastSocket m = new MulticastSocket();
//Check (a) host is designated multicast node for this interface
// (b) receivers exist
for all this.getInterfaces() {
if(designatedHost(this.interface) &&
childrenSet(this.interface,
URI("ham:opaque:news@cnn.com")) != NULL) {
m.addInterface(this.interface);
}
}
while(true) {
m.send(URI("ham:opaque:news@cnn.com"),message);
}
]]></artwork>
</figure>
</section>
<section title="Support of Multi-Resolution Multicast">
<t>Multi-resolution multicast adjusts the multicast stream to
consider heterogeneous end devices. The multicast data (e.g.,
available by different compression levels) is typically announced
using multiple multicast addresses that are unrelated to each other.
Using the common API, multi-resolution multicast can be implemented
transparently by an operator with the help of Name-to-Address
mapping, or by systematic naming in a subscriber-centric
perspective.</t>
<t><list style="hanging">
<t hangText="Operator-Centric:">An operator deploys a
domain-specific mapping. In this case, any multicast receiver
(e.g., mobile or DSL user) subscribes to the same multicast
name, which will be resolved locally to different multicast
addresses. In this case, each Group Address describes a
different level of data quality.</t>
<t hangText="Subscriber-Centric:">In a subscriber-centric
example, the multicast receiver chooses the quality in advance,
based on a predefined naming syntax. Consider a layered video
stream "blockbuster" available at different qualities Q_i, each
of which consists of the base layer plus the sum of EL_j, j
<= i enhancement layers. Each individual layer may then be
accessible by a name "EL_j.Q_i.blockbuster", j <= i, while a
specific quality aggregates the corresponding layers to
"Q_i.blockbuster", and the full-size movie may be just called
"blockbuster".</t>
</list></t>
</section>
</section>
</section>
<section title="Terminology">
<t>This document uses the terminology as defined for the multicast
protocols <xref target="RFC2710"></xref>,<xref
target="RFC3376"></xref>,<xref target="RFC3810"></xref>,<xref
target="RFC4601"></xref>,<xref target="RFC4604"></xref>. In addition,
the following terms will be used.</t>
<t><list style="hanging">
<t hangText="Group Address:">A Group Address is a routing
identifier. It represents a technological specifier and thus
reflects the distribution technology in use. Multicast packet
forwarding is based on this address.</t>
<t hangText="Group Name:">A Group Name is an application identifier
used by applications to manage communication in a multicast group
(e.g., join/leave and send/receive). The Group Name does not
predefine any distribution technologies. Even if it syntactically
corresponds to an address, it solely represents a logical
identifier.</t>
<t hangText="Multicast Namespace:">A Multicast Namespace is a
collection of designators (i.e., names or addresses) for groups that
share a common syntax. Typical instances of namespaces are IPv4 or
IPv6 multicast addresses, overlay group IDs, group names defined on
the application layer (e.g., SIP or email), or some human readable
string.</t>
<t hangText="Interface:">An Interface is a forwarding instance of a
distribution technology on a given node. For example, the IP
Interface 192.168.1.1 at an IPv4 host, or an overlay routing
interface.</t>
<t hangText="Multicast Domain:">A Multicast Domain hosts nodes and
routers of a common, single multicast forwarding technology and is
bound to a single namespace.</t>
<t hangText="Inter-domain Multicast Gateway (IMG):">An Inter-domain
Multicast Gateway (IMG) is an entity that interconnects different
Multicast Domains. Its objective is to forward data between these
domains, e.g., between an IP layer and overlay multicast.</t>
</list></t>
<t></t>
</section>
<section title="Overview">
<t></t>
<section title="Objectives and Reference Scenarios">
<t>The default use case addressed in this document targets at
applications that participate in a group by using some common
identifier taken from some common namespace. This Group Name is
typically learned at runtime from user interaction like the selection
of an IPTV channel, from dynamic session negotiations like in the
Session Initiation Protocol (SIP) <xref target="RFC3261"></xref> or
P2PSIP <xref target="I-D.ietf-p2psip-sip"></xref>, but may as well
have been predefined for an application as a common Group Name.
Technology-specific system functions then transparently map the Group
Name to Group Addresses such that<list style="symbols">
<t>programmers are enabled to process group names in their
programs without the need to consider technological mappings that
relate to designated deployments in target domains;</t>
<t>applications are enabled to identify packets that belong to a
logically named group, independent of the Interface technology
used for sending and receiving packets. The latter shall also hold
for multicast gateways.</t>
</list></t>
<t>This document considers two reference scenarios that cover the
following hybrid deployment cases displayed in <xref
target="fig:reference"></xref>:</t>
<t><list style="numbers">
<t>Multicast Domains running the same multicast technology but
remaining isolated, possibly only connected by network layer
unicast.</t>
<t>Multicast Domains running different multicast technologies but
hosting nodes that are members of the same multicast group.</t>
</list></t>
<figure anchor="fig:reference"
title="Reference scenarios for hybrid multicast, interconnecting group members from isolated homogeneous and heterogeneous domains.">
<artwork><![CDATA[
+-------+ +-------+
| Member| | Member|
| Foo | | G |
+-------+ +-------+
\ /
*** *** *** ***
* ** ** ** *
* *
* MCast Tec A *
* *
* ** ** ** *
*** *** *** ***
+-------+ +-------+ |
| Member| | Member| +-------+
| G | | Foo | | IMG |
+-------+ +-------+ +-------+
| | |
*** *** *** *** *** *** *** ***
* ** ** ** * * ** ** ** *
* * +-------+ * *
* MCast Tec A * --| IMG |-- * MCast Tec B * +------+
* * +-------+ * * -|Member|
* ** ** ** * * ** ** ** * | G |
*** *** *** *** *** *** *** *** +------+
]]></artwork>
</figure>
<t></t>
<!---->
<t></t>
</section>
<section title="Group Communication API and Protocol Stack">
<t>The group communication API abstracts the socket concept and
consists of four parts. Two parts combine the essential communication
functions, while the remaining two offer optional extensions for an
enhanced monitoring and management: <list style="hanging">
<t hangText="Group Management Calls">provide the minimal API to
instantiate aan abstract multicast socket and to manage group
membership;</t>
<t hangText="Send/Receive Calls">provide the minimal API to send
and receive multicast data in a technology-transparent
fashion;</t>
<t hangText="Socket Options">provide extension calls for an
explicit configuration of the multicast socket such as setting hop
limits or associated Interfaces;</t>
<t hangText="Service Calls">provide extension calls that grant
access to internal multicast states of an Interface such as the
multicast groups under subscription or the multicast forwarding
information base.</t>
</list></t>
<t>Multicast applications that use the common API require assistance
by a group communication stack. This protocol stack serves two
needs:</t>
<t><list style="symbols">
<t>It provides system-level support to transfer the abstract
functions of the common API, including namespace support, into
protocol operations at Interfaces;</t>
<t>It provides group communication services across different
multicast technologies at the local host.</t>
</list></t>
<t>A general initiation of a multicast communication in this setting
proceeds as follows:</t>
<t><list style="numbers">
<t>An application opens an abstract multicast socket;</t>
<t>The application subscribes/leaves/(de)registers to a group
using a Group Name;</t>
<t>An intrinsic function of the stack maps the logical group ID
(Group Name) to a technical group ID (Group Address). This
function may make use of deployment-specific knowledge such as
available technologies and group address management in its
domain;</t>
<t>Packet distribution proceeds to and from one or several
multicast-enabled Interfaces.</t>
</list></t>
<t>The abstract multicast socket describes a group communication
channel composed of one or multiple Interfaces. A socket may be
created without explicit Interface association by the application,
which leaves the choice of the underlying forwarding technology to the
group communication stack. However, an application may also bind the
socket to one or multiple dedicated Interfaces, which predefines the
forwarding technology and the Multicast Namespace(s) of the Group
Address(es).</t>
<t>Applications are not required to maintain mapping states for Group
Addresses. The group communication stack accounts for the mapping of
the Group Name to the Group Address(es) and vice versa. Multicast data
passed to the application will be augmented by the corresponding Group
Name. Multiple multicast subscriptions thus can be conducted on a
single multicast socket without the need for Group Name encoding at
the application side.</t>
<t>Hosts may support several multicast protocols. The group
communication stack discovers available multicast-enabled Interfaces.
It provides a minimal hybrid function that bridges data between
different Interfaces and Multicast Domains. Details of service
discovery are out of scope of this document.</t>
<t><!--In this case, they will be enabled to forward data between the different technologies using the service calls of the API. Such a proxy function can be implemented on each host or on dedicated gateways. These gateways also assist multicast members that have no middleware support to be integrated in additional namespaces.--></t>
<t>The extended multicast functions can be implemented by a middleware
as conceptually presented in <xref
target="fig:middleware"></xref>.</t>
<t></t>
<figure anchor="fig:middleware"
title="Architecture of a group communication stack with a middleware offering uniform access to multicast in underlay and overlay">
<artwork><![CDATA[*-------* *-------*
| App 1 | | App 2 |
*-------* *-------*
| |
*---------------------* ---|
| Middleware | |
*---------------------* |
| | |
*---------* | |
| Overlay | | \ Group Communication
*---------* | / Stack
| | |
| | |
*---------------------* |
| Underlay | |
*---------------------* ---|]]></artwork>
</figure>
<t></t>
<t></t>
</section>
<section title="Naming and Addressing">
<t>Applications use Group Names to identify groups. Names can uniquely
determine a group in a global communication context and hide
technological deployment for data distribution from the application.
In contrast, multicast forwarding operates on Group Addresses. Even
though both identifiers may be identical in symbols, they carry
different meanings. They may also belong to different Multicast
Namespaces. The Namespace of a Group Address reflects a routing
technology, while the Namespace of a Group Name represents the context
in which the application operates.</t>
<t>URIs <xref target="RFC3986"></xref> are a common way to represent
Namespace-specific identifiers in applications in the form of an
abstract meta-data type. Throughout this document, all Group Names
follows a URI notation with the syntax defined in <xref
target="sec:details-uri"></xref>. Examples are, ham:ip:224.1.2.3:5000
for a canonical IPv4 ASM group at UDP port 5000, ham:sip:news@cnn.com
for an application-specific naming with service instantiator and
default port selection.</t>
<t>An implementation of the group communication stack can provide
convenience functions that detect the Namespace of a Group Name or
further optimize service instantiation. In practice, such a library
would provide support for high-level data types to the application,
similar to some versions of the current socket API (e.g., InetAddress
in Java). Using this data type could implicitly determine the
Namespace. Details of automatic Namespace identification or service
handling are out of scope of this document.</t>
</section>
<section anchor="sec-namespace" title="Namespaces">
<t>Namespace identifiers in URIs are placed in the scheme element and
characterize syntax and semantic of the group identifier. They enable
the use of convenience functions and high-level data types while
processing URIs. When used in names, they may indicate an application
context, or facilitate a default mapping and a recovery of names from
addresses. They characterize its type, when used in addresses.</t>
<t>Compliant to the URI concept, namespace-schemes can be added.
Examples of schemes are generic (see <xref
target="sec-generic-ns"></xref>) or inherited from applications (see
<xref target="sec-app-ns"></xref>).</t>
</section>
<section title="Name-to-Address Mapping">
<t>The multicast communication paradigm requires all group members to
subscribe to the same Group Name, taken from a common Multicast
Namespace, and thereby to identify the group in a technology-agnostic
way. Following this common API, a sender correspondingly registers a
Group Name prior to transmission.</t>
<t>At communication end points, Group Names require a mapping to Group
Addresses prior to service instantiation at its Interface(s).
Similarly, a mapping is needed at gateways to translate between Group
Addresses from different namespaces consistently. Two requirements
need to be met by a mapping function that translates between Multicast
Names and Addresses.</t>
<t><list style="letters">
<t>For a given Group Name, identify an Address that is appropriate
for a local distribution instance.</t>
<t>For a given Group Address, invert the mapping to recover the
Group Name.</t>
</list></t>
<t>In general, mappings can be complex and do not need to be
invertible. A mapping can be realized by embedding smaller namespaces
into larger, or by selecting an arbitrary, unused ID in a smaller
target namespace. For example, it is not obvious how to map a large
identifier space (e.g., IPv6) to a smaller, collision-prone set like
IPv4 (see <xref
target="I-D.venaas-behave-v4v6mc-framework"></xref><xref
target="I-D.venaas-behave-mcast46">, </xref>, <xref
target="RFC6219"></xref>). Mapping functions can be stateless in some
contexts, but may require states in others. The application of such
functions depends on the cardinality of the namespaces, the structure
of address spaces, and possible address collisions. However, some
namespaces facilitate a canonical, invertible transformation to
default address spaces.</t>
<section title="Canonical Mapping">
<t>Some Multicast Namespaces defined in <xref
target="sec-namespace"></xref> can express a canonical default
mapping. For example, ham:ip:224.1.2.3:5000 indicates the
correspondence to 224.1.2.3 in the default IPv4 multicast address
space at port 5000. This default mapping is bound to a technology
and may not always be applicable, e.g., in the case of address
collisions. Note that under canonical mapping, the multicast URI can
be completely recovered from any data message received within this
group.</t>
</section>
<section title="Mapping at End Points">
<t>Multicast listeners or senders require a Name-to-Address
conversion for all technologies they actively run in a group. Even
though a mapping applies to the local Multicast Domain only, end
points may need to learn a valid Group Address from neighboring
nodes, e.g., from a gateway in the collision-prone IPv4 domain. Once
set, an end point will always be aware of the Name-to-Address
correspondence and thus can autonomously invert the mapping.</t>
</section>
<section title="Mapping at Inter-domain Multicast Gateways">
<t>Multicast data may arrive at an IMG in one technology, requesting
the gateway to re-address packets for another distribution system.
At initial arrival, the IMG may not have explicit knowledge of the
corresponding Multicast Group Name. To perform a consistent mapping,
the group name needs to be acquired. It may have been distributed at
source registration, or may have been learned from a neighboring
node, details of which are beyond the scope of this document.</t>
</section>
</section>
<section title="A Note on Explicit Multicast (XCAST)">
<t>In Explicit Multicast (XCAST) <xref target="RFC5058"></xref>, the
multicast source explicitly pre-defines the receivers. From a
conceptual perspective, XCAST is an additional distribution technology
(i.e., a new technology-specific interface) for this API. XCAST
requires aggregated knowledge of receivers that is available at the
origin of the distribution tree. The instantiation part of the Group
Name may refer to such a management instance and tree root, which can
be the source or some co-located processor.</t>
<t>An implementation of XCAST then requires a topology-dependent
mapping of the Group Name to the set of subscribers. Defining details
of this multi-destination mapping is out of scope of this
document.</t>
</section>
<section title="MTU Handling">
<t>This API considers a multi-technology scenario, in which different
technologies may have different Maximum Transmission Unit (MTU) sizes.
Even if the MTU size between two hosts has been determined, it may
change over time either initiated by the network (e.g., path changes)
or by end hosts (e.g., interface change due to mobility).</t>
<t>The design of this API is based on the objective of robust
communication and easy application development. The MTU handling and
the placement of fragmentation is thus guided by the following
observations.</t>
<t><list style="hanging">
<t hangText="Application">Application programmers need a simple
way to transmit packets in a technology-agnostic fashion. For
this, it is convenient at the time of coding to rely on a
transparent maximum amount of data that can be sent in one message
from a socket. A regular program flow should not be distracted by
querying and changing MTU sizes. Technically, the configuration of
the maximum message size used by the application programmer may
change and disrupt communication, when (a) interfaces will be
added or excluded, or (b) the path MTU changes during transmission
and thus disables the corresponding interfaces.</t>
<t hangText="Middleware">A middleware situated between application
and technology interfaces ensures a general ability of packet
handling, which prevents the application programmer to implement
fragmentation. A uniform maximum message size shall be guaranteed
by the group communication stack (e.g., middleware), which is not
allowed to change during runtime. The latter would conflict with a
technology-agnostic development.</t>
<t hangText="Technology Interfaces">Fragmentation requirements
depends on the technology in use. Hence, the (technology-bound)
interfaces need to copel with MTU sizes that may vary among
interfaces and along different paths.</t>
</list>The concept of this API also aims at guaranteeing a maximum
message size for the application programmer, thereby to handle
fragmentation at the interface level, if needed. Nevertheless, the
application programmer should be able to determine the
technology-specific atomic message size to optimize data distribution
or for other reasons.</t>
<t>The uniform maximum message size should take realistic values
(e.g., following IP clients) to enable smooth and efficient services.
A detailed selection scheme of MTU values is out of scope of this
document.</t>
</section>
</section>
<section anchor="sec:capi" title="Common Multicast API">
<t></t>
<section title="Notation">
<t>The following description of the common multicast API is expressed
in pseudo syntax. Variables that are passed to function calls are
declared by "in", return values are declared by "out". A list of
elements is denoted by "<>". The pseudo syntax assumes that
lists include an attribute which represents the number of
elements.</t>
<t>The corresponding C signatures are defined in <xref
target="sec:c-signatures"></xref>.</t>
</section>
<section anchor="sec:details-uri" title="URI Scheme Definition">
<t>Multicast Names and Multicast Addresses used in this API are
represented by a URI scheme that is specified in the following
subsections.</t>
<section anchor="sec:syntax-uri" title="Syntax">
<t>The syntax of the multicast URI is described by Augmented
Backus-Naur Form (ABNF) <xref target="RFC5234"></xref> and is
defined as follows:</t>
<t><list style="hanging">
<t hangText="ham-URI ">= ham-scheme ":" namespace ":" group [
"@" instantiation ] [ ":" port ] [ "/" sec-credentials ]</t>
</list></t>
<t></t>
<texttable align="left" style="none">
<preamble></preamble>
<ttcol></ttcol>
<ttcol>ham-scheme</ttcol>
<ttcol>= "ham" ; hybrid adaptive multicast</ttcol>
<c></c>
<c>namespace</c>
<c>= ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )</c>
<c></c>
<c>group</c>
<c>= "*" / 1*unreserved ; unreserved from <xref
target="RFC3986"></xref></c>
<c></c>
<c>instantiation</c>
<c>= 1*unreserved ; unreserved from <xref
target="RFC3986"></xref></c>
<c></c>
<c>port</c>
<c>= 1*DIGIT</c>
<c></c>
<c>sec-credentials</c>
<c>= alg ";" val</c>
<c></c>
<c>alg</c>
<c>= 1*unreserved ; unreserved from <xref
target="RFC3986"></xref></c>
<c></c>
<c>val</c>
<c>= 1*unreserved ; unreserved from <xref
target="RFC3986"></xref></c>
<postamble></postamble>
</texttable>
<t>Percent-encoding is applied to dinstinguish between reserved and
unreserved assignments of the same character in the same ham-URI
component (cf., <xref target="RFC3986"></xref>).</t>
</section>
<section anchor="sec:semantic-uri" title="Semantic">
<t>The semantic of the different parts of the URI is defined as
follows:</t>
<t><list style="hanging">
<t hangText="ham-scheme">refers to the specification of the
assigned identifier "ham".</t>
<t hangText="namespace">takes the role of the Multicast
Namespace. It defines the syntax of the group and instantiation
part of the ham-URI. A basic syntax for these elements is
specified in <xref target="sec:syntax-uri"></xref>. The
namespace may further restrict the syntax of designators.
Example namespaces are described in <xref
target="sec-generic-ns"></xref> and <xref
target="sec-app-ns"></xref>.</t>
<t hangText="group">uniquely identifies the group within the
Multicast Namespace given in namespace. The literally "*"
describes all members of the Multicast Group.</t>
<t hangText="instantiation">identifies the entity that generates
the instance of the group (e.g., a SIP domain or a source in
SSM, a dedicated routing entity or a named processor that
accounts for the group communication), using syntax and semantic
as defined by the Namespace. This parameter is optional. Note
that ambiguities (e.g., identical node addresses in multiple
overlay instances) can be distinguished by ports.</t>
<t hangText="port">identifies a specific application at an
instance of a group. This parameter is optional.</t>
<t hangText="sec-credentials">used to implement security
mechanisms (e.g., to authorize Multicast Group access or
authenticate multicast operations). This parameter is optional.
The alg-part describes the security algorithm in use. The
val-part describes the actual value for authentification,
authorization, and accounting. Note that security credentials
may carry a distinct technical meaning w.r.t. AAA schemes and
may differ between group members. Hence the sec-credentials are
not considered part of the Group Name.</t>
</list></t>
</section>
<section anchor="sec-generic-ns" title="Generic Namespaces">
<t><list style="hanging">
<t hangText="IP">This namespace is comprised of regular IP node
naming, i.e., DNS names and addresses taken from any version of
the Internet Protocol. The syntax of the group and instantiation
follows the "host" definition in <xref target="RFC3986"></xref>,
Section 3.2.2. A processor dealing with the IP namespace is
required to determine the syntax (DNS name, IP address, version)
of the group and instantiation expression.</t>
<t hangText="SHA-2">This namespace carries address strings
compliant to SHA-2 hash digests. The syntax of the group and
instantiation follows the "val" definition in <xref
target="RFC6920"></xref>, Section 3. A processor handling those
strings is required to determine the length of the expressions
and passes appropriate values directly to a corresponding
overlay.</t>
<t hangText="Opaque">This namespace transparently carries
strings without further syntactical information, meanings, or
associated resolution mechanism. The corresponding syntax for
the group and instantation part of the ham-URI is defined in
<xref target="sec:syntax-uri"></xref>.</t>
</list></t>
</section>
<section anchor="sec-app-ns" title="Application-centric Namespaces">
<t><list style="hanging">
<t hangText="SIP">The SIP namespace is an example of an
application layer scheme that bears inherent group functions
(conferencing). SIP conference URIs may be directly exchanged
and interpreted at the application, and mapped to group
addresses on the system level to generate a corresponding
multicast group. The syntax of the group and instantiation is
described by the "userinfo" in <xref target="RFC3261"></xref>,
Section 25.1.</t>
<t hangText="RELOAD">This namespace covers address strings
immediately valid in a RELOAD <xref
target="I-D.ietf-p2psip-base"></xref> overlay network. A
processor handling those strings may pass these values directly
to a corresponding overlay that may manage multicast
distribution according to <xref
target="I-D.irtf-samrg-sam-baseline-protocol"></xref>.</t>
</list></t>
</section>
<section title="Future Namespaces">
<t>The concept of the Common Multicast API allows for any namespace
that complies with the superset syntax defined in <xref
target="sec:syntax-uri"></xref>. This document specifies a basic set
of Multicast namespaces in <xref target="sec-generic-ns"></xref> and
<xref target="sec-app-ns"></xref>. If additional namespaces are
needed in the future, a registry for these namespaces should be
created. All namespaces defined in this document should then also be
assigned to the registry.</t>
</section>
</section>
<section title="Additional Abstract Data Types">
<t></t>
<section title="Interface">
<t>The Interface denotes the layer and instance on which the
corresponding call takes effect. In agreement with <xref
target="RFC3493"></xref>, we identify an Interface by an identifier,
which is a positive integer starting at 1.</t>
<t>Properties of an Interface are stored in the following data
structure:</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ struct ifProp {
UnsignedInt if_index; /* 1, 2, ... */
String *ifName; /* "eth0", "eth1:1", "lo", ... */
String *ifAddr; /* "1.2.3.4", "abc123", ... */
String *ifTech; /* "ip", "overlay", ... */
};]]></artwork>
</figure>
<t></t>
<t>The following function retrieves all available Interfaces from
the system:</t>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ getInterfaces(out Interface <ifs>);]]></artwork>
</figure>
<t>It extends the functions for Interface Identification defined in
Section 4 of <xref target="RFC3493"></xref> and can be implemented
by:</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ struct ifProp(out IfProp <ifsProps>);]]></artwork>
</figure>
<t></t>
</section>
<section anchor="sec:membership-events" title="Membership Events">
<t>A membership event is triggered by a multicast state change,
which is observed by the current node. It is related to a specific
Group Name and may be receiver or source oriented.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ eventType {
joinEvent;
leaveEvent;
newSourceEvent;
};
event {
EventType event;
Uri groupName;
Interface if;
};
]]></artwork>
</figure>
<t></t>
<t>An event will be created by the group communication stack and
passed to applications that have registered for events.</t>
</section>
</section>
<section title="Group Management Calls">
<t></t>
<section title="Create">
<t>The create call initiates a multicast socket and provides the
application programmer with a corresponding handle. If no Interfaces
will be assigned based on the call, the default Interface will be
selected and associated with the socket. The call returns an error
code in the case of failures, e.g., due to a non-operational
communication middleware.<spanx style="verbatim"></spanx></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ createMSocket(in Interface <ifs>,
out Socket s);]]></artwork>
<postamble></postamble>
</figure>
<t>The ifs argument denotes a list of Interfaces (if_indexes) that
will be associated with the multicast socket. This parameter is
optional.</t>
<t>On success, a multicast socket identifier is returned, otherwise
NULL.</t>
</section>
<section title="Delete">
<t>The delete call removes the multicast socket.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ deleteMSocket(in Socket s, out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket for
destruction.</t>
<t>On success, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Join">
<t>The join call initiates a subscription for the given Group Name.
Depending on the Interfaces that are associated with the socket,
this may result in an IGMP/MLD report or overlay subscription, for
example.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ join(in Socket s, in Uri groupName, out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The groupName argument identifies the group.</t>
<t>On success, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Leave">
<t>The leave call results in an unsubscription for the given Group
Name.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ leave(in Socket s, in Uri groupName, out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The groupName identifies the group.</t>
<t>On success, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Source Register">
<t>The srcRegister call registers a source for a Group on all active
Interfaces of the socket s. This call may assist group distribution
in some technologies, for example the creation of sub-overlays or
may facilitate a name-to-address mapping. Likewise, it may remain
without effect in some multicast technologies.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ srcRegister(in Socket s, in Uri groupName,
out Interface <ifs>, out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The groupName argument identifies the multicast group to which a
source intends to send data.</t>
<t>The ifs argument points to the list of Interface indexes for
which the source registration failed. A NULL pointer is returned, if
the list is empty. This parameter is optional.</t>
<t>If source registration succeeded for all Interfaces associated
with the socket, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Source Deregister">
<t>The srcDeregister indicates that a source does no longer intend
to send data to the multicast group. This call may remain without
effect in some multicast technologies.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ srcDeregister(in Socket s, in Uri groupName,
out Interface <ifs>, out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The group_name argument identifies the multicast group to which a
source has stopped to send multicast data.</t>
<t>The ifs argument points to the list of Interfaces for which the
source deregistration failed. A NULL pointer is returned, if the
list is empty.</t>
<t>If source deregistration succeeded for all Interfaces associated
with the socket, the out parameter error is 0, otherwise -1.</t>
</section>
</section>
<section title="Send and Receive Calls">
<t></t>
<section title="Send">
<t>The send call passes multicast data destined for a Multicast Name
from the application to the multicast socket.<spanx
style="verbatim"></spanx></t>
<t>It is worth noting that it is the choice of the programmer to
send data via one socket per group or to use a single socket for
multiple groups.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ send(in Socket s, in Uri groupName,
in Size msgLen, in Msg msgBuf,
out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The groupName argument identifies the group to which data will be
sent.</t>
<t>The msgLen argument holds the length of the message to be
sent.</t>
<t>The msgBuf argument passes the multicast data to the multicast
socket.</t>
<t>On success, the out parameter error is 0, otherwise -1. A message
that is too long is indicated by an implementation-specific error
code (e.g., EMSGSIZE in C).</t>
</section>
<section title="Receive">
<t>The receive call passes multicast data and the corresponding
Group Name to the application. This may come in a blocking or
non-blocking variant.<spanx style="verbatim"></spanx></t>
<t>It is worth noting that it is the choice of the programmer to
receive data via one socket per group or to use a single socket for
multiple groups.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ receive(in Socket s, out Uri groupName,
out Size msgLen, out Msg msgBuf,
out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The group_name argument identifies the multicast group for which
data was received.</t>
<t>The msgLen argument holds the length of the received message.</t>
<t>The msgBuf argument points to the payload of the received
multicast data.</t>
<t>On success, the out parameter error is 0, otherwise -1. A message
that is too long is indicated by an implementation-specific error
handling (e.g., EMSGSIZE).</t>
</section>
</section>
<section title="Socket Options">
<t>The following calls configure an existing multicast socket.</t>
<section title="Get Interfaces">
<t>The getInterface call returns an array of all available multicast
communication Interfaces associated with the multicast socket.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ getInterfaces(in Socket s,
out Interface <ifs>, out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The ifs argument points to an array of Interface index
identifiers.</t>
<t>On success, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Add Interface">
<t>The addInterface call adds a distribution channel to the socket.
This may be an overlay or underlay Interface, e.g., IPv6 or DHT.
Multiple Interfaces of the same technology may be associated with
the socket.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ addInterface(in Socket s, in Interface if,
out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s and if arguments identify a multicast socket and Interface,
respectively.</t>
<t>On success, the value 0 is returned, otherwise -1.</t>
</section>
<section title="Delete Interface">
<t>The delInterface call removes the Interface if from the multicast
socket.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ delInterface(in Socket s, Interface if,
out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s and if arguments identify a multicast socket and Interface,
respectively.</t>
<t>On success, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Set TTL">
<t>The setTTL call configures the maximum hop count for the socket a
multicast message is allowed to traverse.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ setTTL(in Socket s, in Int h,
in Interface <ifs>,
out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s and h arguments identify a multicast socket and the maximum
hop count, respectively.</t>
<t>The ifs argument points to an array of Interface index
identifiers. This parameter is optional.</t>
<t>On success, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Get TTL">
<t>The getTTL call returns the maximum hop count a multicast message
is allowed to traverse for the socket.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ getTTL(in Socket s,
out Int h, out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies a multicast socket.</t>
<t>The h argument holds the maximum number of hops associated with
socket s.</t>
<t>On success, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Atomic Message Size">
<t>The getAtomicMsgSize function returns the maximum message size
that an application is allowed to transmit per socket at once
without fragmentation. This value depends on the interfaces
associated with the socket in use and thus may change during
runtime.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ getAtomicMsgSize(in Socket s,
out Int return);]]></artwork>
<postamble></postamble>
</figure>
<t>On success, the function returns a positive value of appropriate
message size, otherwise -1.</t>
</section>
</section>
<section title="Service Calls">
<t></t>
<section title="Group Set">
<t>The groupSet call returns all multicast groups registered at a
given Interface. This information can be provided by group
management states or routing protocols. The return values
distinguish between sender and listener states.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ struct GroupSet {
Uri groupName; /* registered multicast group */
Unt type; /* 0 = listener state, 1 = sender state,
2 = sender & listener state */
}
groupSet(in Interface if,
out GroupSet <groupSet>, out Int error);
]]></artwork>
<postamble></postamble>
</figure>
<t>The if argument identifies the Interface for which states are
maintained.</t>
<t>The groupSet argument points to a list of group states.</t>
<t>On success, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Neighbor Set">
<t>The neighborSet function returns the set of neighboring nodes for
a given Interface as seen by the multicast routing protocol.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ neighborSet(in Interface if,
out Uri <neighborsAddresses>, out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The if argument identifies the Interface for which neighbors are
inquired.</t>
<t>The neighborsAddresses argument points to a list of neighboring
nodes on a successful return.</t>
<t>On success, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Children Set">
<t>The childrenSet function returns the set of child nodes that
receive multicast data from a specified Interface for a given group.
For a common multicast router, this call retrieves the multicast
forwarding information base per Interface.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ childrenSet(in Interface if, in Uri groupName,
out Uri <childrenAddresses>, out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The if argument identifies the Interface for which children are
inquired.</t>
<t>The groupName argument defines the multicast group for which
distribution is considered.</t>
<t>The childrenAddresses argument points to a list of neighboring
nodes on a successful return.</t>
<t>On success, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Parent Set">
<t>The parentSet function returns the set of neighbors from which
the current node receives multicast data at a given Interface for
the specified group.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ parentSet(in Interface if, in Uri groupName,
out Uri <parentsAddresses>, out Int error);]]></artwork>
<postamble></postamble>
</figure>
<t>The if argument identifies the Interface for which parents are
inquired.</t>
<t>The groupName argument defines the multicast group for which
distribution is considered.</t>
<t>The parentsAddresses argument points to a list of neighboring
nodes on a successful return.</t>
<t>On success, the out parameter error is 0, otherwise -1.</t>
</section>
<section title="Designated Host">
<t>The designatedHost function inquires whether this host has the
role of a designated forwarder resp. querier, or not. Such an
information is provided by almost all multicast protocols to prevent
packet duplication, if multiple multicast instances serve on the
same subnet.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ designatedHost(in Interface if, in Uri groupName
out Int return);]]></artwork>
<postamble></postamble>
</figure>
<t>The if argument identifies the Interface for which designated
forwarding is inquired.</t>
<t>The groupName argument specifies the group for which the host may
attain the role of designated forwarder.</t>
<t>The function returns 1 if the host is a designated forwarder or
querier, otherwise 0. The return value -1 indicates an error.</t>
</section>
<section title="Enable Membership Events">
<t>The enableEvents function registers an application at the group
communication stack to receive information about group changes.
State changes are the result of new receiver subscriptions or leaves
as well as of source changes. Upon receiving an event, the group
service may obtain additional information from further service
calls.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ enableEvents();]]></artwork>
<postamble></postamble>
</figure>
<t>Calling this function, the stack starts to pass membership events
to the application. Each event includes an event type identifier and
a Group Name (cf., <xref
target="sec:membership-events"></xref>).</t>
<t>The multicast protocol has not to support membership tracking to
enable this feature. This function can also be implemented at the
middelware layer.</t>
</section>
<section title="Disable Membership Events">
<t>The disableEvents function deactivates the information about
group state changes.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ disableEvents();]]></artwork>
<postamble></postamble>
</figure>
<t>On success, the stack will not pass membership events to the
application.</t>
</section>
<section title="Maximum Message Size">
<t>The getMaxMsgSize function returns the maximum message size that
an application is allowed to transmit per socket at once. This value
is statically guaranteed by the group communication stack.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ getMaxMsgSize(out Int return);]]></artwork>
<postamble></postamble>
</figure>
<t>On success, the function returns a positive value of allowed
message size, otherwise -1.</t>
</section>
</section>
</section>
<section title="Implementation">
<t>A reference implementation of the Common API for Transparent Hybrid
Multicast is available with the HAMcast stack <xref
target="hamcast-dev"> </xref> <xref target="GC2010"></xref> <xref
target="LCN2012"></xref>. This open-source software supports the
multicast API (C++ and Java library) for group application development,
the middleware as a user space system service, and several
multicast-technology modules. The middleware is implemented in C++.</t>
<t>This API is verified and adjusted based on the real-world experiences
gathered in the HAMcast project, and by additional users of the
stack.</t>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>This document specifies the "ham" URI scheme and requests IANA
registration as "Permanent URI Schemes" according to <xref
target="RFC4395"></xref>.</t>
<t></t>
<texttable align="left" style="none">
<preamble></preamble>
<ttcol></ttcol>
<ttcol></ttcol>
<c>URI scheme name</c>
<c>ham</c>
<c></c>
<c></c>
<c>Status</c>
<c>permanent</c>
<c></c>
<c></c>
<c>URI scheme syntax</c>
<c>See <xref target="sec:syntax-uri"></xref>.</c>
<c></c>
<c></c>
<c>URI scheme semantics</c>
<c>See <xref target="sec:semantic-uri"></xref>.</c>
<c></c>
<c></c>
<c>Encoding considerations</c>
<c><xref target="sec:syntax-uri"></xref></c>
<c></c>
<c></c>
<c>Applications/protocols that use this URI scheme name</c>
<c>The scheme is used by multicast applications to access multicast
content.</c>
<c></c>
<c></c>
<c>Interoperability considerations</c>
<c>None</c>
<c></c>
<c></c>
<c>Security considerations</c>
<c>See <xref target="Security"></xref>.</c>
<c></c>
<c></c>
<c>Contact</c>
<c>Matthias Waehlisch, mw@link-lab.net</c>
<c></c>
<c></c>
<c>Author/Change controller</c>
<c>IRTF</c>
<c></c>
<c></c>
<c>References</c>
<c>As specified in this document.</c>
<postamble></postamble>
</texttable>
</section>
<section anchor="Security" title="Security Considerations">
<t>This draft does neither introduce additional messages nor novel
protocol operations.</t>
</section>
<section anchor="Acknowledgements" title="Acknowledgements">
<t>We would like to thank the HAMcast-team, Nora Berg, Gabriel Hege,
Fabian Holler, Alexander Knauf, Sebastian Meiling, Sebastian Woelke, and
Sebastian Zagaria, at the HAW Hamburg for many fruitful discussions and
for their continuous critical feedback while implementing the common
multicast API and a hybrid multicast middleware. Special thanks to
Dominik Charousset of the HAMcast-team for in-depth perspectives on the
matter of code. We gratefully acknowledge WeeSan, Mario Kolberg, and
John Buford for reviewing and their suggestions to improve the document.
We would like to thank the Name-based socket BoF (in particular Dave
Thaler) for clarifying insights into the question of meta function
calls. We thank Lisandro Zambenedetti Granville and Tony Li for very
careful reviews of the pre-final versions of this document. Barry Leiba
and Graham Klyne provided very constructive input to find a suitable URI
scheme. They are gratefully acknowledged.</t>
<t>This work is partially supported by the German Federal Ministry of
Education and Research within the HAMcast project (see
http://hamcast.realmv6.org), which is part of G-Lab.</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include="reference.RFC.2119"?>
<?rfc include="reference.RFC.3493"?>
<?rfc include="reference.RFC.3678"?>
<?rfc include="reference.RFC.1075"?>
<?rfc include="reference.RFC.5015"?>
<?rfc include="reference.RFC.3810"?>
<?rfc include="reference.RFC.4604"?>
<?rfc include="reference.RFC.2710"?>
<?rfc include="reference.RFC.4601"?>
<?rfc include="reference.RFC.3376"?>
<?rfc include="reference.RFC.3986"?>
<?rfc include="reference.RFC.5234"?>
<?rfc include="reference.RFC.3261"?>
<?rfc include="reference.RFC.4395"?>
<?rfc include="reference.RFC.5058"?>
<?rfc include="reference.RFC.6920"?>
</references>
<references title="Informative References">
<?rfc include="reference.RFC.5757"?>
<?rfc include="reference.RFC.6219"?>
<?rfc include="reference.I-D.venaas-behave-v4v6mc-framework"?>
<?rfc include="reference.I-D.venaas-behave-mcast46"?>
<?rfc include="reference.I-D.ietf-mboned-auto-multicast"?>
<?rfc include="reference.I-D.ietf-p2psip-sip"?>
<?rfc include="reference.I-D.ietf-p2psip-base"?>
<?rfc include="reference.I-D.irtf-samrg-sam-baseline-protocol"?>
<reference anchor="hamcast-dev"
target="http://hamcast.realmv6.org/developers">
<front>
<title>HAMcast developers</title>
<author></author>
<date />
</front>
</reference>
<reference anchor="GC2010">
<front>
<title>System-assisted Service Evolution for a Future Internet - The
HAMcast Approach to Pervasive Multicast</title>
<author fullname="Sebastian Meiling" initials="S." surname="Meiling"></author>
<author fullname="Dominik Charousset" initials="D."
surname="Charousset"></author>
<author fullname="Thomas C. Schmidt" initials="T.C."
surname="Schmidt"></author>
<author fullname="Matthias Waehlisch" initials="M."
surname="Waehlisch"></author>
<date month="December" year="2010" />
</front>
<seriesInfo name="Proc. of IEEE GLOBECOM 2010 Workshops."
value="MCS 2010, pp. 938-942, Piscataway, NJ, USA: IEEE Press" />
</reference>
<reference anchor="LCN2012">
<front>
<title>Large-Scale Measurement and Analysis of One-Way Delay in
Hybrid Multicast Networks</title>
<author fullname="Sebastian Meiling" initials="S." surname="Meiling"></author>
<author fullname="Thomas C. Schmidt" initials="T.C."
surname="Schmidt"></author>
<author fullname="Matthias Waehlisch" initials="M."
surname="Waehlisch"></author>
<date month="October" year="2012" />
</front>
<seriesInfo name="Proc. of 37th Annual IEEE Conference on Local Computer Networks (LCN 2012)."
value="Piscataway, NJ, USA: IEEE Press" />
</reference>
</references>
<section anchor="sec:c-signatures" title="C Signatures">
<t>This section describes the C signatures of the common multicast API,
which are defined in <xref target="sec:capi"></xref>.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int createMSocket(int* result, size_t num_ifs, const uint32_t* ifs);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int deleteMSocket(int s);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int join(int msock, const char* group_uri);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int leave(int msock, const char* group_uri);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int srcRegister(int msock,
const char* group_uri,
size_t num_ifs,
uint32_t* ifs);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int srcDeregister(int msock,
const char* group_uri,
size_t num_ifs,
uint32_t* ifs);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int send(int msock,
const char* group_uri,
size_t buf_len,
const void* buf);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int receive(int msock,
const char* group_uri,
size_t buf_len,
void* buf);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int getInterfaces(int msock,
size_t* num_ifs,
uint32_t** ifs);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int addInterface(int msock, uint32_t iface);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int delInterface(int msock, uint32_t iface);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int setTTL(int msock, uint8_t value,
size_t num_ifs, uint32_t* ifs);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int getTTL(int msock, uint8_t* result);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int getAtomicMsgSize(int msock);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ typedef struct {
char* group_uri; /* registered mcast group */
int type; /* 0: listener state,
1: sender state
2: sender and listener state */
}
GroupSet;
int groupSet(uint32_t iface,
size_t* num_groups,
GroupSet** groups);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int neighborSet(uint32_t iface,
const char* group_name,
size_t* num_neighbors,
char** neighbor_uris);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int childrenSet(uint32_t iface,
const char* group_name,
size_t* num_children,
char** children_uris);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int parentSet(uint32_t iface,
const char* group_name,
size_t* num_parents,
char** parents_uris);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int designatedHost(uint32_t iface,
const char* group_name);]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ typedef void (*MembershipEventCallback)
(int, /* event type */
uint32_t, /* interface id */
const char*); /* group uri */
int registerEventCallback(MembershipEventCallback callback);
int envableEvents();
int disableEvents();]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int getMaxMsgSize();]]></artwork>
<postamble></postamble>
</figure>
<t></t>
</section>
<section title="Use Case for the API">
<t>For the sake of readability, we demonstrate developing using the API
based on a high-level Java-like syntax; we do not consider error
handling</t>
<figure>
<artwork><![CDATA[ -- Application above middleware:
//Initialize multicast socket;
//the middleware selects all available interfaces
MulticastSocket m = new MulticastSocket();
m.join(URI("ham:ip:224.1.2.3:5000"));
m.join(URI("ham:ip:[FF02:0:0:0:0:0:0:3]:6000"));
m.join(URI("ham:sip:news@cnn.com"));
-- Middleware:
join(URI mcAddress) {
//Select interfaces in use
for all this.interfaces {
switch (interface.type) {
case "ipv6":
//... map logical ID to routing address
Inet6Address rtAddressIPv6 = new Inet6Address();
mapNametoAddress(mcAddress,rtAddressIPv6);
interface.join(rtAddressIPv6);
case "ipv4":
//... map logical ID to routing address
Inet4Address rtAddressIPv4 = new Inet4Address();
mapNametoAddress(mcAddress,rtAddressIPv4);
interface.join(rtAddressIPv4);
case "sip-session":
//... map logical ID to routing address
SIPAddress rtAddressSIP = new SIPAddress();
mapNametoAddress(mcAddress,rtAddressSIP);
interface.join(rtAddressSIP);
case "dht":
//... map logical ID to routing address
DHTAddress rtAddressDHT = new DHTAddress();
mapNametoAddress(mcAddress,rtAddressDHT);
interface.join(rtAddressDHT);
//...
}
}
}
]]></artwork>
</figure>
</section>
<section title="Deployment Use Cases for Hybrid Multicast">
<t>This section describes the application of the defined API to
implement an IMG.</t>
<section title="DVMRP">
<t>The following procedure describes a transparent mapping of a
DVMRP-based any source multicast service to another many-to-many
multicast technology, e.g., an overlay.</t>
<t>An arbitrary DVMRP <xref target="RFC1075"></xref> router will not
be informed about new receivers, but will learn about new sources
immediately. The concept of DVMRP does not provide any central
multicast instance. Thus, the IMG can be placed anywhere inside the
multicast region, but requires a DVMRP neighbor connectivity. Thus the
group communication stack used by the IMG is enhanced by a DVMRP
implementation. New sources in the underlay will be advertised based
on the DVMRP flooding mechanism and received by the IMG. Based on
this, the event "new_source_event" is created and passed to the
application. The relay agent initiates a corresponding join in the
native network and forwards the received source data towards the
overlay routing protocol. Depending on the group states, the data will
be distributed to overlay peers.</t>
<t>DVMRP establishes source specific multicast trees. Therefore, a
graft message is only visible to DVMRP routers on the path from the
new receiver subnet to the source, but in general not to an IMG. To
overcome this problem, data of multicast senders in the overlay may
become noticeable via the Source Register call, as well as by an IMG
that initiates an an all-group join in the overlay using the namespace
extension of the API. Each IMG is initially required to forward the
data received in the overlay to the underlay, independent of native
multicast receivers. Subsequent prunes may limit unwanted data
distribution thereafter.</t>
</section>
<section title="PIM-SM">
<t>The following procedure describes a transparent mapping of a
PIM-SM-based any source multicast service to another many-to-many
multicast technology, e.g., an overlay.</t>
<t>The Protocol Independent Multicast Sparse Mode (PIM-SM) <xref
target="RFC4601"></xref> establishes rendezvous points (RP). These
entities receive listener subscriptions and source registering of a
domain. For a continuous update an IMG has to be co-located with an
RP. Whenever PIM register messages are received, the IMG must signal
internally a new multicast source using the event "new_source_event".
Subsequently, the IMG joins the group and a shared tree between the RP
and the sources will be established, which may change to a source
specific tree after PIM switches to phase three. Source traffic will
be forwarded to the RP based on the IMG join, even if there are no
further receivers in the native multicast domain. Designated routers
of a PIM-domain send receiver subscriptions towards the PIM-SM RP. The
reception of such messages initiates the event "join_event" at the
IMG, which initiates a join towards the overlay routing protocol.
Overlay multicast data arriving at the IMG will then transparently be
forwarded in the underlay network and distributed through the RP
instance.</t>
</section>
<section title="PIM-SSM">
<t>The following procedure describes a transparent mapping of a
PIM-SSM-based source specific multicast service to another one-to-many
multicast technology, e.g., an overlay.</t>
<t>PIM Source Specific Multicast (PIM-SSM) is defined as part of
PIM-SM and admits source specific joins (S,G) according to the source
specific host group model <xref target="RFC4604"></xref>. A multicast
distribution tree can be established without the assistance of a
rendezvous point.</t>
<t>Sources are not advertised within a PIM-SSM domain. Consequently,
an IMG cannot anticipate the local join inside a sender domain and
deliver a priori the multicast data to the overlay instance. If an IMG
of a receiver domain initiates a group subscription via the overlay
routing protocol, relaying multicast data fails, as data is not
available at the overlay instance. The IMG instance of the receiver
domain, thus, has to locate the IMG instance of the source domain to
trigger the corresponding join. In agreement with the objectives of
PIM-SSM, the signaling should not be flooded in underlay and
overlay.</t>
<t>A solution can be to intercept the subscription at both, source and
receiver sites: To monitor multicast receiver subscriptions
("join_event" or "leave_event") in the underlay, the IMG is placed on
path towards the source, e.g., at a domain border router. This router
intercepts join messages and extracts the unicast source address S,
initializing an IMG specific join to S via regular unicast. Multicast
data arriving at the IMG of the sender domain can be distributed via
the overlay. Discovering the IMG of a multicast sender domain may be
implemented analogously to AMT <xref
target="I-D.ietf-mboned-auto-multicast"></xref> by anycast.
Consequently, the source address S of the group (S,G) should be built
based on an anycast prefix. The corresponding IMG anycast address for
a source domain is then derived from the prefix of S.</t>
</section>
<section title="BIDIR-PIM">
<t>The following procedure describes a transparent mapping of a
BIDIR-PIM-based any source multicast service to another many-to-many
multicast technology, e.g., an overlay.</t>
<t>Bidirectional PIM <xref target="RFC5015"></xref> is a variant of
PIM-SM. In contrast to PIM-SM, the protocol pre-establishes
bidirectional shared trees per group, connecting multicast sources and
receivers. The rendezvous points are virtualized in BIDIR-PIM as an
address to identify on-tree directions (up and down). Routers with the
best link towards the (virtualized) rendezvous point address are
selected as designated forwarders for a link-local domain and
represent the actual distribution tree. The IMG is to be placed at the
RP-link, where the rendezvous point address is located. As source data
in either cases will be transmitted to the rendezvous point link, the
BIDIR-PIM instance of the IMG receives the data and can internally
signal new senders towards the stack via the "new_source_event". The
first receiver subscription for a new group within a BIDIR-PIM domain
needs to be transmitted to the RP to establish the first branching
point. Using the "join_event", an IMG will thereby be informed about
group requests from its domain, which are then delegated to the
overlay.</t>
</section>
</section>
<section title="Change Log">
<t>The following changes have been made from
draft-irtf-samrg-common-api-08</t>
<t><list style="numbers">
<t>Redefinition of the URI scheme</t>
</list>The following changes have been made from
draft-irtf-samrg-common-api-07<list style="numbers">
<t>Editorial polishing following Tony's review</t>
</list> The following changes have been made from
draft-irtf-samrg-common-api-06</t>
<t><list style="numbers">
<t>Editorial comments from Lisandro included</t>
<t>Syntax notation in Section 4.2.2, 4.2.3, an 4.6.1 improved</t>
<t>Appendix A improved</t>
</list>The following changes have been made from
draft-irtf-samrg-common-api-05</t>
<t><list style="numbers">
<t>Added preparations for IRSG review</t>
<t>Fixed error codes</t>
<t>Editorial improvements</t>
<t>Updated references</t>
</list>The following changes have been made from
draft-irtf-samrg-common-api-04</t>
<t><list style="numbers">
<t>Added section "A Note on Explicit Multicast (XCAST)"</t>
<t>Added section "MTU Handling"</t>
<t>Added socket option getAtomicMSgSize</t>
<t>Added service call getMaxMsgSize</t>
</list>The following changes have been made from
draft-irtf-samrg-common-api-03</t>
<t><list style="numbers">
<t>Added section "Illustrative Example"</t>
<t>Added section "Implementation"</t>
<t>Minor clarifications</t>
</list>The following changes have been made from
draft-irtf-samrg-common-api-02</t>
<t><list style="numbers">
<t>Added use case of multicast flavor support</t>
<t>Restructured Section 3</t>
<t>Major update on namespaces and on mapping</t>
<t>C signatures completed</t>
<t>Many clarifications and editorial improvements</t>
</list> The following changes have been made from
draft-irtf-samrg-common-api-01</t>
<t><list style="numbers">
<t>Pseudo syntax for lists objects changed</t>
<t>Editorial improvements</t>
</list>The following changes have been made from
draft-irtf-samrg-common-api-00</t>
<t><list style="numbers">
<t>Incorrect pseudo code syntax fixed</t>
<t>Minor editorial improvements</t>
</list>The following changes have been made from
draft-waehlisch-sam-common-api-06</t>
<t><list style="numbers">
<t>no changes; draft adopted as WG document (previous
draft-waehlisch-sam-common-api-06, now
draft-irtf-samrg-common-api-00)</t>
</list>The following changes have been made from
draft-waehlisch-sam-common-api-05</t>
<t><list style="numbers">
<t>Description of the Common API using pseudo syntax added</t>
<t>C signatures of the Comon API moved to appendix</t>
<t>updateSender() and updateListener() calls replaced by events</t>
<t>Function destroyMSocket renamed as deleteMSocket.</t>
</list>The following changes have been made from
draft-waehlisch-sam-common-api-04</t>
<t><list style="numbers">
<t>updateSender() added.</t>
</list>The following changes have been made from
draft-waehlisch-sam-common-api-03<list style="numbers">
<t>Use cases added for illustration.</t>
<t>Service calls added for inquiring on the multicast distribution
system.</t>
<t>Namespace examples added.</t>
<t>Clarifications and editorial improvements.</t>
</list>The following changes have been made from
draft-waehlisch-sam-common-api-02<list style="numbers">
<t>Rename init() in createMSocket().</t>
<t>Added calls srcRegister()/srcDeregister().</t>
<t>Rephrased API calls in C-style.</t>
<t>Cleanup code in "Practical Example of the API".</t>
<t>Partial reorganization of the document.</t>
<t>Many editorial improvements.</t>
</list></t>
<t>The following changes have been made from
draft-waehlisch-sam-common-api-01<list style="numbers">
<t>Document restructured to clarify the realm of document overview
and specific contributions s.a. naming and addressing.</t>
<t>A clear separation of naming and addressing was drawn. Multicast
URIs have been introduced.</t>
<t>Clarified and adapted the API calls.</t>
<t>Introduced Socket Option calls.</t>
<t>Deployment use cases moved to an appendix.</t>
<t>Simple programming example added.</t>
<t>Many editorial improvements.</t>
</list></t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 13:37:55 |