*-------*     *-------*     
| App 1 |     | App 2 |
*-------*     *-------*
    |             |
*---------------------*         ---|
|   Middleware        |            |
*---------------------*            |
     |          |                  |
*---------*     |                  |   
| Overlay |     |                   \  Group Communication
*---------*     |                   /  Stack
     |          |                  |
     |          |                  |
*---------------------*            |
|   Underlay          |            |
*---------------------*         ---|

Figure 3: Architecture of a group communication stack with a middleware offering uniform access to multicast in underlay and overlay

3.3. Naming and Addressing

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.

URIs [RFC3986] 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 Section 4.2.1. Examples are, ip://224.1.2.3:5000 for a canonical IPv4 ASM group at UDP port 5000, sip://news@cnn.com for an application-specific naming with service instantiator and default port selection.

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.

3.4. Namespaces

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.

Compliant to the URI concept, namespace-schemes can be added. Examples of schemes are generic or inherited from applications.

3.4.1. Generic Namespaces

IP

This namespace is comprised of regular IP node naming, i.e., DNS names and addresses taken from any version of the Internet Protocol. A processor dealing with the IP namespace is required to determine the syntax (DNS name, IP address version) of the group expression.

SHA-2

This namespace carries address strings compliant to SHA-2 hash digests. A processor handling those strings is required to determine the length of the group expression and passes appropriate values directly to a corresponding overlay.

Opaque

This namespace transparently carries strings without further syntactical information, meanings, or associated resolution mechanism.

3.4.2. Application-centric Namespaces

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.

RELOAD

This namespace covers address strings immediately valid in a RELOAD [I-D.ietf-p2psip-base] overlay network. A processor handling those strings may pass these values directly to a corresponding overlay.

3.5. Name-to-Address Mapping

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.

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.

1. For a given Group Name, identify an Address that is appropriate for a local distribution instance.
2. For a given Group Address, invert the mapping to recover the Group Name.

In general, mapping can be complex and does 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 [I-D.venaas-behave-v4v6mc-framework][I-D.venaas-behave-mcast46], [RFC6219] ). 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.

3.5.1. Canonical Mapping

Some Multicast Namespaces defined in Section 3.4 can express a canonical default mapping. For example, 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 from this group.

3.5.2. Mapping at End Points

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.

3.5.3. Mapping at Inter-domain Multicast Gateways

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.

3.6. A Note on Explicit Multicast (XCAST)

In Explicit Multicast (XCAST) [RFC5058], 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. The instantiation part of the Group Name may refer to multiple receivers. However, from an implementation perspective, this specification defines the syntax of the Group Name according to [RFC3986], which does not support a set of (sub-)identifiers. Extending [RFC3986] is out of scope of this document.

Implementing XCAST without a set representation in the Group Name requires a topology-dependent mapping of the Name to a set of subscribers. Defining these details is out of scope of this document.

3.7. MTU Handling

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).

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.

Application

The application programmer needs a simple way to send packets in a technology-agnostic fashion. Therefore it is convenient to be clear at the time of coding what maximum amount of data can be sent per socket in one message. A regular program flow should not be distracted by 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.

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 maximum message size guaranteed by the group communication stack (e.g., middleware) is not allowed to change during runtime, as this would conflict with technology-agnostic development.

Technology Interfaces

Fragmentation depends on the technology in use. The (technology-bound) interfaces, thus, need to deal with MTU sizes that may vary among interfaces and along different paths.

The concept of this API also aims to guarantee 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.

The 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.

4. Common Multicast API

4.1. Notation

The following description of the common multicast API is described 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.

The corresponding C signatures are defined in Appendix A.

4.2. Abstract Data Types

4.2.1. Multicast URI

Multicast Names and Multicast Addresses used in this API follow an URI scheme that defines a subset of the generic URI specified in [RFC3986] and is syntactically compliant with the guidelines given in [RFC4395].

The multicast URI is defined as follows:

• scheme "://" group "@" instantiation ":" port "/" sec-credentials

The parts of the URI are defined as follows:

scheme

refers to the specification of the assigned identifier [RFC3986] which takes the role of the Multicast Namespace.

group

uniquely identifies the group within the Namespace given in scheme.

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 given in scheme. This parameter is optional. Note that ambiguities (e.g., identical node addresses in multiple overlay instances) can be distinguished by ports.

port

identifies a specific application at an instance of a group. This parameter is optional.

sec-credentials

used to implement optional security credentials (e.g., to authorize a multicast group access). 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.

4.2.2. Interface

The Interface denotes the layer and instance on which the corresponding call will be effective. In agreement with [RFC3493], we identify an Interface by an identifier, which is a positive integer starting at 1.

Properties of an Interface are stored in the following data structure:

    struct ifProp {
      UnsignedInt if_index; /* 1, 2, ... */
      String        *ifName;  /* "eth0", "eth1:1", "lo", ... */
      String        *ifAddr;  /* "1.2.3.4", "abc123", ... */
      String        *ifTech;  /* "ip", "overlay", ... */                 
    };

The following function retrieves all available Interfaces from the system:

    getInterfaces(out Interface <ifs>);

It extends the functions for Interface Identification defined in Section 4 of [RFC3493] and can be implemented by:

    struct ifProp(out IfProp <ifsProps>);

4.2.3. Membership Events

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.

    eventType {
            joinEvent;
            leaveEvent;
            newSourceEvent;
    };

    event { 
           EventType event;
           Uri groupName;
           Interface if;
    };

An event will be created by the group communication stack and passed to applications that have registered for events.

4.3. Group Management Calls

4.3.1. Create

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.

    createMSocket(in Interface <ifs>, 
                  out Socket s);

The ifs argument denotes a list of Interfaces (if_indexes) that will be associated with the multicast socket. This parameter is optional.

On success, a multicast socket identifier is returned, otherwise NULL.

4.3.2. Delete

The delete call removes the multicast socket.

    deleteMSocket(in Socket s, out Int error);

The s argument identifies the multicast socket for destruction.

On success, the out parameter error is 0, otherwise -1.

4.3.3. Join

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.

    join(in Socket s, in Uri groupName, out Int error);

The s argument identifies the multicast socket.

The groupName argument identifies the group.

On success, the out parameter error is 0, otherwise -1.

4.3.4. Leave

The leave call results in an unsubscription for the given Group Name.

    leave(in Socket s, in Uri groupName, out Int error);

The s argument identifies the multicast socket.

The groupName identifies the group.

On success, the out parameter error is 0, otherwise -1.

4.3.5. Source Register

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.

    srcRegister(in Socket s, in Uri groupName, 
                out Interface <ifs>, out Int error);

The s argument identifies the multicast socket.

The groupName argument identifies the multicast group to which a source intends to send data.

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.

If source registration succeeded for all Interfaces associated with the socket, the out parameter error is 0, otherwise -1.

4.3.6. Source Deregister

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.

    srcDeregister(in Socket s, in Uri groupName,
                  out Interface <ifs>, out Int error);

The s argument identifies the multicast socket.

The group_name argument identifies the multicast group to which a source has stopped to send multicast data.

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.

If source deregistration succeeded for all Interfaces associated with the socket, the out parameter error is 0, otherwise -1.

4.4. Send and Receive Calls

4.4.1. Send

The send call passes multicast data destined for a Multicast Name from the application to the multicast socket.

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.

    send(in Socket s, in Uri groupName, 
         in Size msgLen, in Msg msgBuf,
         out Int error);

The s argument identifies the multicast socket.

The groupName argument identifies the group to which data will be sent.

The msgLen argument holds the length of the message to be sent.

The msgBuf argument passes the multicast data to the multicast socket.

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).

4.4.2. Receive

The receive call passes multicast data and the corresponding Group Name to the application. This may come in a blocking or non-blocking variant.

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.

    receive(in Socket s, out Uri groupName, 
            out Size msgLen, out Msg msgBuf,
            out Int error);

The s argument identifies the multicast socket.

The group_name argument identifies the multicast group for which data was received.

The msgLen argument holds the length of the received message.

The msgBuf argument points to the payload of the received multicast data.

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).

4.5. Socket Options

The following calls configure an existing multicast socket.

4.5.1. Get Interfaces

The getInterface call returns an array of all available multicast communication Interfaces associated with the multicast socket.

    getInterfaces(in Socket s, 
                  out Interface <ifs>, out Int error);

The s argument identifies the multicast socket.

The ifs argument points to an array of Interface index identifiers.

On success, the out parameter error is 0, otherwise -1.

4.5.2. Add Interface

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.

    addInterface(in Socket s, in Interface if,
                 out Int error);

The s and if arguments identify a multicast socket and Interface, respectively.

On success, the value 0 is returned, otherwise -1.

4.5.3. Delete Interface

The delInterface call removes the Interface if from the multicast socket.

    delInterface(in Socket s, Interface if,
                 out Int error);

The s and if arguments identify a multicast socket and Interface, respectively.

On success, the out parameter error is 0, otherwise -1.

4.5.4. Set TTL

The setTTL call configures the maximum hop count for the socket a multicast message is allowed to traverse.

    setTTL(in Socket s, in Int h,
           in Interface <ifs>,
           out Int error);

The s and h arguments identify a multicast socket and the maximum hop count, respectively.

The ifs argument points to an array of Interface index identifiers. This parameter is optional.

On success, the out parameter error is 0, otherwise -1.

4.5.5. Get TTL

The getTTL call returns the maximum hop count a multicast message is allowed to traverse for the socket.

    getTTL(in Socket s, 
           out Int h, out Int error);

The s argument identifies a multicast socket.

The h argument holds the maximum number of hops associated with socket s.

On success, the out parameter error is 0, otherwise -1.

4.5.6. Atomic Message Size

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.

    getAtomicMsgSize(in Socket s,
                     out Int return);

On success, the function returns a positive value of appropriate message size, otherwise -1.

4.6. Service Calls

4.6.1. Group Set

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.

    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);

The if argument identifies the Interface for which states are maintained.

The groupSet argument points to a list of group states.

On success, the out parameter error is 0, otherwise -1.

4.6.2. Neighbor Set

The neighborSet function returns the set of neighboring nodes for a given Interface as seen by the multicast routing protocol.

    neighborSet(in Interface if,
                out Uri <neighborsAddresses>, out Int error);

The if argument identifies the Interface for which neighbors are inquired.

The neighborsAddresses argument points to a list of neighboring nodes on a successful return.

On success, the out parameter error is 0, otherwise -1.

4.6.3. Children Set

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.

    childrenSet(in Interface if, in Uri groupName, 
                out Uri <childrenAddresses>, out Int error);

The if argument identifies the Interface for which children are inquired.

The groupName argument defines the multicast group for which distribution is considered.

The childrenAddresses argument points to a list of neighboring nodes on a successful return.

On success, the out parameter error is 0, otherwise -1.

4.6.4. Parent Set

The parentSet function returns the set of neighbors from which the current node receives multicast data at a given Interface for the specified group.

    parentSet(in Interface if, in Uri groupName, 
              out Uri <parentsAddresses>, out Int error);

The if argument identifies the Interface for which parents are inquired.

The groupName argument defines the multicast group for which distribution is considered.

The parentsAddresses argument points to a list of neighboring nodes on a successful return.

On success, the out parameter error is 0, otherwise -1.

4.6.5. Designated Host

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.

    designatedHost(in Interface if, in Uri groupName
                   out Int return);

The if argument identifies the Interface for which designated forwarding is inquired.

The groupName argument specifies the group for which the host may attain the role of designated forwarder.

The function returns 1 if the host is a designated forwarder or querier, otherwise 0. The return value -1 indicates an error.

4.6.6. Enable Membership Events

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.

    enableEvents();

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., Section 4.2.3).

The multicast protocol has not to support membership tracking to enable this feature. This function can also be implemented at the middelware layer.

4.6.7. Disable Membership Events

The disableEvents function deactivates the information about group state changes.

    disableEvents();

On success, the stack will not pass membership events to the application.

4.6.8. Maximum Message Size

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.

    getMaxMsgSize(out Int return);

On success, the function returns a positive value of allowed message size, otherwise -1.

5. Implementation

A reference implementation of the Common API for Transparent Hybrid Multicast is available with the HAMcast stack [hamcast-dev] [GC2010] [LCN2012]. This open-source software supports the multicast API (C++ and Java library) for group application development, the middleware as a userspace system service, and several multicast-technology modules. The middleware is implemented in C++.

This API is verified and adjusted based on the real-world experiences gathered in the HAMcast project, and by additional users of the stack.

6. IANA Considerations

This document makes no request of IANA.

7. Security Considerations

This draft does neither introduce additional messages nor novel protocol operations.

8. Acknowledgements

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 for a very careful review of the pre-final version of this document.

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.

9. Informative References

, "

[RFC2119]	Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3493]	Gilligan, R., Thomson, S., Bound, J., McCann, J. and W. Stevens, "Basic Socket Interface Extensions for IPv6", RFC 3493, February 2003.
[RFC3678]	Thaler, D., Fenner, B. and B. Quinn, "Socket Interface Extensions for Multicast Source Filters", RFC 3678, January 2004.
[RFC1075]	Waitzman, D., Partridge, C. and S. Deering, "Distance Vector Multicast Routing Protocol", RFC 1075, November 1988.
[RFC5015]	Handley, M., Kouvelas, I., Speakman, T. and L. Vicisano, "Bidirectional Protocol Independent Multicast (BIDIR-PIM)", RFC 5015, October 2007.
[RFC3810]	Vida, R. and L. Costa, "Multicast Listener Discovery Version 2 (MLDv2) for IPv6", RFC 3810, June 2004.
[RFC4604]	Holbrook, H., Cain, B. and B. Haberman, "Using Internet Group Management Protocol Version 3 (IGMPv3) and Multicast Listener Discovery Protocol Version 2 (MLDv2) for Source-Specific Multicast", RFC 4604, August 2006.
[RFC2710]	Deering, S., Fenner, W. and B. Haberman, "Multicast Listener Discovery (MLD) for IPv6", RFC 2710, October 1999.
[RFC4601]	Fenner, B., Handley, M., Holbrook, H. and I. Kouvelas, "Protocol Independent Multicast - Sparse Mode (PIM-SM): Protocol Specification (Revised)", RFC 4601, August 2006.
[RFC3376]	Cain, B., Deering, S., Kouvelas, I., Fenner, B. and A. Thyagarajan, "Internet Group Management Protocol, Version 3", RFC 3376, October 2002.
[RFC3986]	Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.
[RFC3261]	Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, June 2002.
[RFC4395]	Hansen, T., Hardie, T. and L. Masinter, "Guidelines and Registration Procedures for New URI Schemes", BCP 35, RFC 4395, February 2006.
[RFC5757]	Schmidt, T., Waehlisch, M. and G. Fairhurst, "Multicast Mobility in Mobile IP Version 6 (MIPv6): Problem Statement and Brief Survey", RFC 5757, February 2010.
[RFC5058]	Boivie, R., Feldman, N., Imai, Y., Livens, W. and D. Ooms, "Explicit Multicast (Xcast) Concepts and Options", RFC 5058, November 2007.
[RFC6219]	Li, X., Bao, C., Chen, M., Zhang, H. and J. Wu, "The China Education and Research Network (CERNET) IVI Translation Design and Deployment for the IPv4/IPv6 Coexistence and Transition", RFC 6219, May 2011.
[I-D.venaas-behave-v4v6mc-framework]	Venaas, S, Li, X and C Bao, "Framework for IPv4/IPv6 Multicast Translation", Internet-Draft draft-venaas-behave-v4v6mc-framework-03, June 2011.
[I-D.venaas-behave-mcast46]	Venaas, S, Asaeda, H, SUZUKI, S and T Fujisaki, "An IPv4 - IPv6 multicast translator", Internet-Draft draft-venaas-behave-mcast46-02, December 2010.
[I-D.ietf-mboned-auto-multicast]	Bumgardner, G, "Automatic Multicast Tunneling", Internet-Draft draft-ietf-mboned-auto-multicast-14, June 2012.
[I-D.ietf-p2psip-base]	Jennings, C, Lowekamp, B, Rescorla, E, Baset, S and H Schulzrinne, "REsource LOcation And Discovery (RELOAD) Base Protocol", Internet-Draft draft-ietf-p2psip-base-23, November 2012.
[hamcast-dev]	HAMcast developers", .
[GC2010]	Meiling, S., Charousset, D., Schmidt, T.C. and M. Waehlisch, "System-assisted Service Evolution for a Future Internet - The HAMcast Approach to Pervasive Multicast", Proc. of IEEE GLOBECOM 2010 Workshops. MCS 2010, pp. 938-942, Piscataway, NJ, USA: IEEE Press, December 2010.
[LCN2012]	Meiling, S., Schmidt, T.C. and M. Waehlisch, "Large-Scale Measurement and Analysis of One-Way Delay in Hybrid Multicast Networks", Proc. of 37th Annual IEEE Conference on Local Computer Networks (LCN 2012). Piscataway, NJ, USA: IEEE Press, October 2012.

Appendix A. C Signatures

This section describes the C signatures of the common multicast API, which are defined in Section 4.

    int createMSocket(int* result, size_t num_ifs, const uint32_t* ifs);

    int deleteMSocket(int s);

    int join(int msock, const char* group_uri);

    int leave(int msock, const char* group_uri);

    int srcRegister(int msock,
                    const char* group_uri,
                    size_t num_ifs,
                    uint32_t* ifs);

    int srcDeregister(int msock,
                      const char* group_uri,
                      size_t num_ifs,
                      uint32_t* ifs);

    int send(int msock, 
             const char* group_uri,
             size_t buf_len,
             const void* buf);

    int receive(int msock,
                const char* group_uri,
                size_t buf_len,
                void* buf);

    int getInterfaces(int msock,
                      size_t* num_ifs,
                      uint32_t** ifs);

    int addInterface(int msock, uint32_t iface);

    int delInterface(int msock, uint32_t iface);

    int setTTL(int msock, uint8_t value,
               size_t num_ifs, uint32_t* ifs);

    int getTTL(int msock, uint8_t* result);

    int getAtomicMsgSize(int msock);

    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);

    int neighborSet(uint32_t iface,
                    const char* group_name,
                    size_t* num_neighbors,
                    char** neighbor_uris);

    int childrenSet(uint32_t iface,
                    const char* group_name,
                    size_t* num_children,
                    char** children_uris);

    int parentSet(uint32_t iface,
                  const char* group_name,
                  size_t* num_parents,
                  char** parents_uris);

    int designatedHost(uint32_t iface,
                       const char* group_name);

       typedef void (*MembershipEventCallback)(int,          /* event type   */
                                               uint32_t,     /* interface id */
                                               const char*); /* group uri    */

       int registerEventCallback(MembershipEventCallback callback);

       int envableEvents();

       int disableEvents();

    int getMaxMsgSize();

Appendix B. Use Case for the API

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

  -- Application above middleware:

  //Initialize multicast socket; 
  //the middleware selects all available interfaces
  MulticastSocket m = new MulticastSocket();
  
  m.join(URI("ip://224.1.2.3:5000"));
  m.join(URI("ip://[FF02:0:0:0:0:0:0:3]:6000"));
  m.join(URI("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);
         //...
      }
    }
  }

Appendix C. Deployment Use Cases for Hybrid Multicast

This section describes the application of the defined API to implement an IMG.

C.1. DVMRP

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.

An arbitrary DVMRP [RFC1075] 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.

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 noticable 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.

C.2. PIM-SM

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.

The Protocol Independent Multicast Sparse Mode (PIM-SM) [RFC4601] 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.

C.3. PIM-SSM

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.

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 [RFC4604]. A multicast distribution tree can be established without the assistance of a rendezvous point.

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.

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 [I-D.ietf-mboned-auto-multicast] 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.

C.4. BIDIR-PIM

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.

Bidirectional PIM [RFC5015] 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.

Appendix D. Change Log

The following changes have been made from draft-irtf-samrg-common-api-06

1. Editorial comments from Lisandro included
2. Syntax notation in Section 4.2.2, 4.2.3, an 4.6.1 improved
3. Appendix A improved

The following changes have been made from draft-irtf-samrg-common-api-05

1. Added preparations for IRSG review
2. Fixed error codes
3. Editorial improvements
4. Updated references

The following changes have been made from draft-irtf-samrg-common-api-04

1. Added section "A Note on Explicit Multicast (XCAST)"
2. Added section "MTU Handling"
3. Added socket option getAtomicMSgSize
4. Added service call getMaxMsgSize

The following changes have been made from draft-irtf-samrg-common-api-03

1. Added section "Illustrative Example"
2. Added section "Implementation"
3. Minor clarifications

The following changes have been made from draft-irtf-samrg-common-api-02

1. Added use case of multicast flavor support
2. Restructured Section 3
3. Major update on namespaces and on mapping
4. C signatures completed
5. Many clarifications and editorial improvements

The following changes have been made from draft-irtf-samrg-common-api-01

1. Pseudo syntax for lists objects changed
2. Editorial improvements

The following changes have been made from draft-irtf-samrg-common-api-00

1. Incorrect pseudo code syntax fixed
2. Minor editorial improvements

The following changes have been made from draft-waehlisch-sam-common-api-06

1. no changes; draft adopted as WG document (previous draft-waehlisch-sam-common-api-06, now draft-irtf-samrg-common-api-00)

The following changes have been made from draft-waehlisch-sam-common-api-05

1. Description of the Common API using pseudo syntax added
2. C signatures of the Comon API moved to appendix
3. updateSender() and updateListener() calls replaced by events
4. Function destroyMSocket renamed as deleteMSocket.

The following changes have been made from draft-waehlisch-sam-common-api-04

1. updateSender() added.

The following changes have been made from draft-waehlisch-sam-common-api-03

1. Use cases added for illustration.
2. Service calls added for inquiring on the multicast distribution system.
3. Namespace examples added.
4. Clarifications and editorial improvements.

The following changes have been made from draft-waehlisch-sam-common-api-02

1. Rename init() in createMSocket().
2. Added calls srcRegister()/srcDeregister().
3. Rephrased API calls in C-style.
4. Cleanup code in "Practical Example of the API".
5. Partial reorganization of the document.
6. Many editorial improvements.

The following changes have been made from draft-waehlisch-sam-common-api-01

1. Document restructured to clarify the realm of document overview and specific contributions s.a. naming and addressing.
2. A clear separation of naming and addressing was drawn. Multicast URIs have been introduced.
3. Clarified and adapted the API calls.
4. Introduced Socket Option calls.
5. Deployment use cases moved to an appendix.
6. Simple programming example added.
7. Many editorial improvements.

Authors' Addresses