A.2 Documentation Details

26.3473GPPApplication Programming Interface and URLMultimedia Broadcast/Multicast Service (MBMS)Release 17TS

A.2.0 General

A graphical presentation of the interface is encouraged. Figure A.1 shows some examples using an informal notation. The existence of an interface can be implied even without using an explicit symbol for it. If a relationship symbol joins an element/function symbol and the relationship type involves an interaction—as opposed to, say, "is a subclass of," that implies that the interaction takes place through the element’s interface.

Figure A.1: Example Figure for Interface documentation

A.2.1 IDL for Interface Specification

Interface Definition Language (IDL) [9] is a standard language for defining function and method interfaces. It supports common primitive data types. Some of the base data types supported by IDL are int, Boolean, byte, char, double, float, long, short, and void *. IDL also supports signed and unsigned qualifiers, enumerations and more.

IDL’s data types and definitions are both language-neutral and platform-neutral. This enables the definition of a common interface that may be implemented by different modules or components irrespective of the language and platform. An IDL interface provides a description of the functionality that will be provided by an object. It provides all of the information needed to develop clients that use the interface.

While IDL is not a programming language, there are tools that map IDL to just about every major programming language.

Below is a sample IDL definition of "order"

interface order {
float calculate_tax ([in] float taxable_amount);
float calculate_total([in] item_list items);
bool place_order([in,out] item_list items);

A.2.2 IDL as Data Format

IDL is also proposed as the data format for message exchange.

A.2.3 Doxygen for API Semantics

Doxygen is a cross-platform documentation system for C++, Java, C, and IDL, etc. It provides a mechanism to document code syntax and semantics. It allows tagging comments in code that will be used to generate nicely formatted output. Available tags enables capturing methods, parameters, pre and post conditions for calling methods as well as highlighting error condition and exceptions.

Doxygen can be used to generate on-line class browser (in HTML) and/or an off-line reference manual from a set of source files. Below is a sample of Doxygen comments for a function definition.

/** @name binary_search

* @brief Search a array for a value using binary search.
* @param[in] a Array of floats.
* @param[in] n Number of elements of @a a to search.
* @param[in] v Value to search for.
* @return An index into array @a a or -1.
* @pre 0 <= n <= Size of the array @a a.
* @pre For all i,j with 0 <= i < j < @a n, @a a[i] <= @a a[j].
* @post (0 <= result < @a n and @a a[result] == @a v)
* or (result == -1 and there is no i, 0 <= i < @a n, s.t. @a a[i] == @a v).
int binary_search(const float* a, int n, float v)

A.2.4 Use Cases and Message Flows

Message flows (sequence diagrams) are an interaction diagram that shows the objects/modules participating in a particular interaction and the messages they exchange arranged in a time sequence.

Figure A.2: Example Figure for Sequence Diagram

Annex B (informative) :
Interface Definition Language for MBMS-APIs