.. _concepts:

Networking API concepts
=======================

OpenLMI-Networking provides CIM API. Some CIM knowledge is required and this guide assumes that reader can routinely read and modify remote CIM objects and call their intrinsic and extrinsic methods.

Hardware representation
-----------------------

.. _hardware:

There is instance of subclass of :ref:`CIM_NetworkPort <CIM-NetworkPort>` for each physical network device present in the system, e.g. :ref:`LMI_EthernetPort <LMI-EthernetPort>` for ethernet ports.

Instances of class :ref:`LMI_LANEndpoint <LMI-LANEndpoint>` represent communication endpoints, identified by MAC address to which the network port will respond. It's associated to the corresponding instance of :ref:`CIM_NetworkPort <CIM-NetworkPort>` subclass via instance of :ref:`LMI_NetworkDeviceSAPImplementation <LMI-NetworkDeviceSAPImplementation>`.

.. figure:: pic/intro-hardware.svg

Current network configuration
-----------------------------

:ref:`LMI_IPNetworkConnection <LMI-IPNetworkConnection>` instances are representation of the network connection in the system, e.g. "eth0", "p1p1". Instance of this class is associated to :ref:`LMI_LANEndpoint <LMI-LANEndpoint>` via instance of :ref:`LMI_EndpointForIPNetworkConnection <LMI-EndpointForIPNetworkConnection>`.

.. note::
    There are usually 1:1:1 relation between instances of CIM_NetworkPort subclasses, LMI_LANEndpoint instances and LMI_IPNetworkConnection instance in this provider. The classes are implemented for sake of compatibility with DMTF profiles.

:ref:`LMI_IPProtocolEndpoint <LMI-IPProtocolEndpoint>` - there is instance of this class for each IP address on any network device and the instance is associated with :ref:`LMI_IPNetworkConnection <LMI-IPNetworkConnection>` via :ref:`LMI_NetworkSAPSAPDependency <LMI-NetworkSAPSAPDependency>` and with :ref:`LMI_LANEndpoint <LMI-LANEndpoint>` via :ref:`LMI_BindsToLANEndpoint <LMI-BindsToLANEndpoint>`.

Default gateway is represented by instance of :ref:`LMI_NetworkRemoteServiceAccessPoint <LMI-NetworkRemoteServiceAccessPoint>` with attribute ``AccessContext`` equal to ``2 (Default Gateway)``.

Instances of class :ref:`LMI_IPVersionSettingData <LMI-IPVersionSettingData>` represent IPv4 or IPv6 support. If there is instance of this class associated with :ref:`CIM_ComputerSystem <CIM-ComputerSystem>` it means that the system supports IPv4 and/or IPv6 (depending on value of   ProtocolIFType property). Instances of this class can be associated also to :ref:`LMI_IPNetworkConnection <LMI-IPNetworkConnection>`. It means that the network connection supports IPv4 and/or IPv6.

.. figure:: pic/intro-current.svg

Settings
--------

The OpenLMI networking provider is based on concept of ``connections``. ``Connection`` is set of settings that can be applied to interface. Each connection is represented by instance of :ref:`LMI_IPAssignmentSettingData <LMI-IPAssignmentSettingData>` and it is aggregator for detailed settings represented by instances of following classes: :ref:`LMI_DHCPSettingData <LMI-DHCPSettingData>`, :ref:`LMI_DNSSettingData <LMI-DNSSettingData>`, :ref:`LMI_ExtendedStaticIPAssignmentSettingData <LMI-ExtendedStaticIPAssignmentSettingData>`. These detailed setting is associated with master setting via :ref:`LMI_OrderedIPAssignmentComponent <LMI-OrderedIPAssignmentComponent>` where the master has role ``GroupComponent``.

``Connections`` available to port are associated by :ref:`LMI_IPElementSettingData <LMI-IPElementSettingData>`. Its property ``IsCurrent`` is ``1`` when the connection is currently active. Property ``IsDefault`` is ``1`` when the connection is automatically activated.

.. figure:: pic/intro-setting.svg

Altering and applying connections
---------------------------------

Method :ref:`LMI_CreateIPSetting <LMI-IPNetworkConnectionCapabilities-LMI-CreateIPSetting>` of :ref:`LMI_IPNetworkConnectionCapabilites <LMI-IPNetworkConnectionCapabilities>` can be used to create new ``connection``. The ``connection`` will be bonded to :ref:`LMI_IPNetworkConnection <LMI-IPNetworkConnection>` that is associated with given :ref:`LMI_IPNetworkConnectionCapabilites <LMI-IPNetworkConnectionCapabilities>`.

Singleton class :ref:`LMI_IPConfigurationService <LMI-IPConfigurationService>` provides method :ref:`ApplySettingToIPNetworkConnection <LMI-IPConfigurationService-ApplySettingToIPNetworkConnection>` that applies :ref:`LMI_IPAssignmentSettingData <LMI-IPAssignmentSettingData>` to :ref:`LMI_IPNetworkConnection <LMI-IPNetworkConnection>`.