2.3.1.1 Query interface example

Query interface is a type-safe way to achieve a safe downcasting and to allow interfaces to be aggregated to an object. Objects using the query interface must inherit from the Interface base class.

An example of the use of query interface is shown below. Consider a node pointer n0 that points to an InternetNode object with an implementation of IPv4. The client code wishes to configure a default route. To do so, it must access an object within the node that has an interface to the IP forwarding configuration. It performs the following two steps:

  Ptr<IIpv4> ipv4 = n0->QueryInterface<IIpv4> (IIpv4::iid);
  ipv4->SetDefaultRoute (Ipv4Address ("10.1.1.2"), 1);

In the first line a (smart) pointer of type IIpv4 (``interface to IPv4'') is declared and assigned to the result of a QueryInterface on the node for the interface type IIpv4. This pointer value will be returned null if the node doesn't support the requested interface. If non-null, this pointer can be used like a traditional pointer to access the API of the IIpv4 object.

To summarize, two benefits that we expect to leverage from this are as follows:

• Encapsulation: By separating interface from implementation, it permits implementors to replace elements of the protocol stack while remaining compliant with client code that supports the same interface. For example, one type of node may include native ns-3 models of protocols, while another may be a port of a Linux stack, and both may be accessed by the same interface.
• Aggregation: QueryInterface allows for aggregation of interfaces at run time. For instance, an existing Node object may have an ``Energy Model'' object and its interface aggregated to it at run time (without modifying and recompiling the node class). An existing model (such as a wireless net device) can then query interface for the energy model and act appropriately if the interface has been either built in to the underlying Node object or aggregated to it at run time.

We hope that this mode of programming will require much less need for developers to modify the ns-3 base classes or libraries.

See also the samples/main-query-interface.cc program.