Imported Upstream version 1.1.92 upstream/1.1.92

1 files changed, 0 insertions, 478 deletions

diff --git a/docs/api/migrating-to-09.xml b/docs/api/migrating-to-09.xml
deleted file mode 100644
index f282d646..00000000
--- a/docs/api/migrating-to-09.xml
+++ /dev/null
@@ -1,478 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-]>
-<chapter id="ref-migrating">
-  <title>Migrating from NetworkManager 0.8 to NetworkManager 0.9</title>
-
-  <para>
-    NetworkManager 0.9 is a new major version of NetworkManager that breaks
-    both API and ABI compared to previous versions.  These changes are
-    intended to make communication with NetworkManager much simpler, especially
-    for network control and configuration programs.  Thankfully, most changes
-    are not difficult to implement, and the advantages of the simpler
-    architecture of NetworkManager 0.9 greatly outweight the effort of
-    updating client programs.
-  </para>
-
-  <section>
-    <title>Architecture and D-Bus API Changes in 0.9</title>
-
-    <para>
-      This section details the architectural and D-Bus API changes in
-      NetworkManager 0.9.
-    </para>
-
-    <section>
-    <title>Elimination of the User Settings Service</title>
-    <para>
-      Previously there were two "settings services", or D-Bus services that
-      provided and saved network configuration information.  NetworkManager
-      owned the "system" settings service, and one user-level applet owned the
-      "user" settings service.  Now, the "user" settings service has been
-      eliminated, so clients only have to track one D-Bus service to read and
-      update network configuration.  The functionality of the old user settings
-      service has been replaced with a "permissions" key on each connection
-      object to preserve the ability to restrict which users can use the
-      connection, and with a "secret agent" D-Bus API for user-session-level
-      secure storage of network secrets and passwords.
-    </para>
-    <para>
-      Elimination of the user settings service provides the following advantages
-      for clients of NetworkManager:
-      <itemizedlist>
-        <listitem>Simpler discovery of network configuration and change tracking</listitem>
-        <listitem>Simpler storage of user-level network secrets by control applets</listitem>
-        <listitem>Correct operation of fast-user switching and multi-seat configurations</listitem>
-        <listitem>More granular network connection permissions for system administrators</listitem>
-        <listitem>Connections are now system-wide by default (unless restricted by the user or system administrator)</listitem>
-        <listitem>Easier deployment of user-specific connections (ie, VPNs)</listitem>
-      </itemizedlist>
-    </para>
-    <para>
-      With this change, D-Bus methods that previously took a "service name"
-      argument (like
-      <literal>org.freedesktop.NetworkManager.ActivateConnection</literal>) and
-      objects with service name properties (like ActiveConnection objects) no
-      longer have those arguments or properties.
-    </para>
-    <para>
-      <emphasis role="strong">Action:</emphasis> if you develop a network control
-      applet that talks to NetworkManager and used to provide a user settings
-      service, you can eliminate that code and rely on NetworkManager for all
-      storage of network configuration.  Your applet should now implement the
-      Secret Agent D-Bus API (see below) to store user-specific secrets, and
-      add legacy user-specific configuration to NetworkManager when run.  More
-      information about both these changes follows.
-    </para>
-    </section>
-
-    <section>
-    <title>User Secret Agents</title>
-    <para>
-      Even with the elimination of the user settings service, in some cases it
-      is still desirable to store secrets in the user's session and not in
-      system-wide storage (and thus available to all users).  To allow this
-      functionality the concept of agents has been introduced.  Using the new
-      <ulink url="spec.html#org.freedesktop.NetworkManager.AgentManager">
-      <literal>org.freedesktop.NetworkManager.AgentManager</literal></ulink>
-      D-Bus interface provided by NetworkManager, user applications can register
-      themselves as "secret agents", ie programs capable of saving and providing
-      secrets to NetworkManager.  The agent should export the
-      <ulink url="spec.html#org.freedesktop.NetworkManager.SecretAgent">
-      <literal>org.freedesktop.NetworkManager.SecretAgent</literal></ulink>
-      D-Bus interface, but should NOT claim a bus name on the system or session
-      bus.  Instead, NetworkManager talks to the agent directly over the D-Bus
-      connection which the agent used to register itself.
-    </para>
-    <para>
-      Each agent must send a unique identifier to NetworkManager when it
-      registers.  This identifier must follow certain rules (see the NM D-Bus
-      API documentation for more details) but looks essentially the same as
-      a D-Bus service name.  Only one agent using a given identifier may be
-      registered at the same time.  The agent is automatically unregistered
-      if it disconnects from D-Bus or exits.
-    </para>
-    <para>
-      When NetworkManager requires secrets during the attempt to connect to a
-      network, and no secrets are available from the internal settings service,
-      NetworkManager queries each registered agent for secrets.  Agents that
-      are in "active" user sessions (as determined by ConsoleKit) are preferred
-      over inactive ones.  Only agents belonging to users who have permission
-      to view and modify the connection are queried.  For more information on
-      connection permissions, see below.
-    </para>
-      When secrets are requested, the agent is also sent a set of flags that
-      modify the behavior of the request.  By default, the agent should never
-      attempt to query the user for secrets, but should simply return any
-      available saved secrets.  Other flags allow the agent to explicitly
-      request new secrets from the user.
-    <para>
-      <emphasis role="strong">Action:</emphasis> the parts of a previous user
-      settings service that handled secrets may be easily repurposed as the bulk
-      of the implementation of a secret agent.  The agent is sent all available
-      connection settings, and from those should be able to retrieve or save
-      any saved user secrets, or to request new secrets from the user.
-    </para>
-    </section>
-
-    <section>
-    <title>Settings Service Interface Changes</title>
-    <para>
-      With the elimination of the user settings service, the old
-      <literal>org.freedesktop.NetworkManagerUserSettings</literal> and
-      <literal>org.freedesktop.NetworkManagerSystemSettings</literal> D-Bus
-      service names are no longer used.  Instead NetworkManager provides the
-      settings service using its own D-Bus service name,
-      <literal>org.freedesktop.NetworkManager</literal>.  The object path of
-      the settings service has also changed to
-      <literal>/org/freedesktop/NetworkManager/Settings</literal>.
-    </para>
-    <para>
-      Additionally, the D-Bus interface of the settings service has changed
-      to <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
-      <literal>org.freedesktop.NetworkManager.Settings</literal></ulink> from
-      the old interface name of
-      <literal>org.freedesktop.NetworkManagerSettings</literal>, and the old
-      <literal>org.freedesktop.NetworkManagerSettings.System</literal>
-      interface has been merged into the new
-      <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
-      <literal>org.freedesktop.NetworkManager.Settings</literal></ulink> interface
-      as the split no longer made sense. This includes the
-      <literal>SaveHostname</literal> method and the <literal>Hostname</literal>
-      and <literal>CanModify</literal> properties.
-    </para>
-    <para>
-      <emphasis role="strong">Action:</emphasis> change the service name and
-      object path that your application uses to request system network settings
-      to <literal>org.freedesktop.NetworkManager</literal> and
-      <literal>/org/freedesktop/NetworkManager/Settings</literal> respectively,
-      and update the D-Bus interface that codes uses to talk to the settings
-      service to <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
-      <literal>org.freedesktop.NetworkManager.Settings</literal></ulink>.
-      Listen for hostname changes using the new interface name as well.
-    </para>
-    </section>
-
-    <section>
-    <title>Connection Object Interface Changes</title>
-    <para>
-      Consistent with the interface changes to the Settings object, the
-      Connection object's D-Bus interface has changed to
-      <ulink url="spec.html#org.freedesktop.NetworkManager.Settings.Connection">
-      <literal>org.freedesktop.NetworkManager.Settings.Connection</literal></ulink>
-      from the previous 
-      <literal>org.freedesktop.NetworkManagerSettings.Connection</literal>.
-    </para>
-    <para>
-      Additionally, the
-      <literal>org.freedesktop.NetworkManager.Settings.Connection.Updated</literal>
-      signal of the Connection object no longer includes the updated settings
-      data argument, as that might allow users who are not authorized to
-      view the connection details to do so.  Instead, when a client receives the
-      Updated signal, it should requery the Connection's settings with the
-      <literal>org.freedesktop.NetworkManager.Settings.Connection.GetSettings</literal>
-      method.  If the client receives an error as a result of this method call,
-      it should assume the connection has been deleted.
-    </para>
-    <para>
-      <emphasis role="strong">Action:</emphasis> where code manipulates
-      Connection objects, update the D-Bus interface that code uses to be
-      <literal>org.freedesktop.NetworkManager.Settings.Connection</literal>.
-      Additionally, code that listens for the
-      <literal>org.freedesktop.NetworkManager.Settings.Connection.Updated</literal>
-      signal should no longer expect the new settings data as an argument, but
-      instead should request the new settings data using the
-      <literal>org.freedesktop.NetworkManager.Settings.Connection.GetSettings</literal>
-      method.
-    </para>
-    </section>
-
-    <section>
-    <title>Permissions Methods Consolidation</title>
-    <para>
-      Previously there were two D-Bus method calls to retrieve the list of
-      operations that a user client could perform, and two signals notifying
-      callers that they should recheck permissions.  Those two calls were:
-      <itemizedlist>
-        <listitem>
-          <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal>
-          which returned a bitfield of operations the caller was allowed to
-          perform related to modify system network settings and the machine
-          hostname
-        </listitem>
-        <listitem>
-          <literal>org.freedesktop.NetworkManager.GetPermissions</literal> which
-          returned a dictionary mapping permission names to result strings like
-          "yes", "auth", or "no", relating to network control permissions like
-          the ability to enable or disable WiFi.
-        </listitem>
-      </itemizedlist>
-      These two calls have been consolidated into an enhanced
-      <literal>org.freedesktop.NetworkManager.GetPermissions</literal> call that
-      uses the same arguments, but includes all permissions, including those which
-      the settings service used to handle.
-    </para>
-    <para>
-      With this change, the bitfield items from
-      <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal>
-      are now string-based permissions.  The mapping is as follows:
-      <table>
-        <tgroup cols="2">
-          <thead>
-            <row><entry>Old bitfield value</entry><entry>New permission name</entry></row>
-          </thead>
-          <tbody>
-            <row>
-              <entry><screen>0x1 (connection-modify)</screen></entry>
-              <entry>
-                <literal>org.freedesktop.NetworkManager.settings.modify.system</literal>
-                or <literal>org.freedesktop.NetworkManager.settings.modify.system</literal>
-                depending on the permissions of the connection.
-              </entry>
-            </row>
-            <row>
-              <entry><screen>0x2 (wifi-share-protected)</screen></entry>
-              <entry>
-                <literal>org.freedesktop.NetworkManager.wifi.share.protected</literal>
-              </entry>
-            </row>
-            <row>
-              <entry><screen>0x4 (wifi-share-open)</screen></entry>
-              <entry>
-                <literal>org.freedesktop.NetworkManager.wifi.share.open</literal>
-              </entry>
-            </row>
-            <row>
-              <entry><screen>0x8 (hostname-modify)</screen></entry>
-              <entry>
-                <literal>org.freedesktop.NetworkManager.settings.modify.hostname</literal>
-              </entry>
-            </row>
-          </tbody>
-        </tgroup>
-      </table>
-    </para>
-    <para>
-      <emphasis role="strong">Action:</emphasis> modify handling of existing
-      code that checks permissions to recognize the new permissions names for
-      old system settings permissions, and remove code that used to call
-      <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal>.
-    </para>
-    </section>
-
-    <section>
-    <title>AddConnection Returns Object Path of New Connection</title>
-    <para>
-      The <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
-      <literal>org.freedesktop.NetworkManager.Settings.AddConnection</literal>
-      </ulink> method call now returns the object path of the newly added
-      connection. Previously, if code wanted to manipulate a connection
-      post-addition, it had to wait for the new connection to be announced via
-      the NewConnection signal by matching connection UUIDs.  Now the object
-      path is returned and this workaround is no longer required.
-    </para>
-    <para>
-      <emphasis role="strong">Action:</emphasis> update code that adds new
-      connections to handle the object path returned from AddConnection, and
-      remove workarounds for finding the new connection via signals.
-    </para>
-    </section>
-
-    <section>
-    <title>Support for WiMAX Devices</title>
-    <para>
-      NetworkManager now supports Intel WiMAX mobile broadband devices.  A
-      corresponding device type (<literal>NM_DEVICE_TYPE_WIMAX</literal>) and
-      a new <ulink url="spec.html#org.freedesktop.NetworkManager.Device.WiMax">
-      <literal>org.freedesktop.NetworkManager.Device.WiMax</literal></ulink>
-      D-Bus interface have been added.  Furthermore, to support connection to
-      different WiMAX Network Service Providers (NSPs) the
-      <ulink url="spec.html#org.freedesktop.NetworkManager.Device.WiMax.Nsp">
-      <literal>org.freedesktop.NetworkManager.Device.WiMax.Nsp</literal></ulink>
-      interface has been added to access information about each available
-      WiMAX network.
-    </para>
-    <para>
-      <emphasis role="strong">Action:</emphasis> update code that handles
-      devices and/or displays status to users to recognize the new device type,
-      and to display available WiMAX NSPs similar to how WiFi Access Points
-      are displayed. Also update code that creates new connections to allow
-      creation of new WiMAX connections.
-    </para>
-    </section>
-
-    <section>
-    <title>New Device States</title>
-    <para>
-      A few <ulink url="spec.html#type-NM_DEVICE_STATE">new device states</ulink>
-      have been added, and all device states have been renumbered for flexibility.
-      The new devices states IP_CHECK, SECONDARIES, and DEACTIVATING.
-    </para>
-    <para>
-      <emphasis role="strong">Action:</emphasis> where code checks device state
-      or shows UI indication of the device's state, make sure the new device
-      states are processed correctly, and that code in switch()-type statements
-      is updated to handle the new states.
-    </para>
-    </section>
-
-    <section>
-    <title>New Active Connection State</title>
-    <para>
-      Along with the new device states, an
-      <ulink url="spec.html#type-NM_ACTIVE_CONNECTION_STATE">additional
-      ActiveConnection state</ulink> has been added: DEACTIVATING.  This state
-      is entered when the connection is being torn down and deactivated.
-    </para>
-    <para>
-      <emphasis role="strong">Action:</emphasis> where code checks active
-      connection states or shows UI indication of active connection states, make
-      sure the DEACTIVATING state is processed correctly, and that code in
-      switch()-type statements is updated to handle it.
-    </para>
-    </section>
-
-    <section>
-    <title>Consolidated Modem Devices</title>
-    <para>
-      Many new mobile broadband devices support multiple access families, like
-      Qualcomm Gobi cards (CDMA/EVDO and GSM/UMTS), or multi-mode EVDO/LTE
-      or UMTS/LTE modems like the Pantech UML290.  The previous hard split
-      between CDMA/EVDO and GSM/UMTS device classes was not flexible enough to
-      deal with these new multi-mode devices.  Thus the previously separate
-      CDMA and GSM device classes have been combined into a single Modem
-      device class, which exposes both hardware "ModemCapabilities" and
-      runtime "CurrentCapabilities" which represent generic access technology
-      families like CDMA/EVDO, GSM/UMTS, and LTE which the device supports.
-      ModemCapabilities indicate all the access technology families which the
-      modem is capable of supporting, while CurrentCapabilities indicate the
-      immediate access technology families the device supports without reloading
-      the firmware and thus restarting the device.
-    </para>
-    <para>
-      Along with this change, the
-      <literal>org.freedesktop.NetworkManager.Device.Serial</literal>
-      interface has been removed as it's functionality will be incorporated
-      into the 
-      <ulink url="spec.html#org.freedesktop.NetworkManager.Device.Modem">
-      <literal>org.freedesktop.NetworkManager.Device.Modem</literal></ulink>
-      interface in the future.
-    </para>
-    <para>
-      <emphasis role="strong">Action:</emphasis> combine code that checks for
-      the old CDMA and GSM device types, and instead handle the new Modem device
-      type.  Where behavior must change based on the capabilities of the device,
-      check the CurrentCapabilities device property to determine whether to
-      treat the device as CDMA, GSM, or LTE for purposes of configuration and
-      status.
-    </para>
-    </section>
-
-    <section>
-    <title>Secret Property Flags</title>
-    <para>
-      In the Connection object's configuration properties, each setting's secret
-      properties (like WiFi passphrases, or public key passwords, etc) now has
-      an associated "flags" property that changes how NetworkManager treats the
-      secret.  The "flags" property is a bitfield of one or more of the
-      following values:
-      <table>
-        <tgroup cols="2">
-          <thead>
-            <row><entry>Flag Value</entry><entry>Meaning</entry></row>
-          </thead>
-          <tbody>
-            <row>
-              <entry><screen>0x00 (none)</screen></entry>
-              <entry>
-                NetworkManager is responsible for providing and storing this
-                secret (default)
-              </entry>
-            </row>
-            <row>
-              <entry><screen>0x01 (agent-owned)</screen></entry>
-              <entry>
-                A user secret agent is responsible for providing and storing
-                this secret; when it is required agents will be asked to
-                retrieve it
-              </entry>
-            </row>
-            <row>
-              <entry><screen>0x02 (not saved)</screen></entry>
-              <entry>
-                The secret is not saved, and should be requested each time it
-                is required.  Used for OTP/token configurations where the
-                secret changes periodically, or if the user simply wants to
-                manually enter the secret each time.
-              </entry>
-            </row>
-            <row>
-              <entry><screen>0x04 (not required)</screen></entry>
-              <entry>
-                In situations where it cannot be automatically determined that
-                the secret is required (some VPNs and PPP providers dont require
-                all possible secrets) this flag indicates that the specific
-                secret is not required.
-              </entry>
-            </row>
-          </tbody>
-        </tgroup>
-      </table>
-    </para>
-    <para>
-      <emphasis role="strong">Action:</emphasis> user interface code which
-      handles entry of connection secrets should be updated to read and set
-      secret flags.  For example, code that creates new VPN connections may want
-      to set the "agent-owned" flag to ensure that the user's VPN password is
-      not available to all users.  EAP-TLS and VPN interface code might add a
-      checkbox that toggles the "not saved" bit to indicate that the
-      password/PIN code should be requested from a hardware token each time it
-      is required.
-    </para>
-    </section>
-
-    <section>
-    <title>Deprecated Methods Removed</title>
-    <para>
-      A few methods and signals of the <literal>org.freedesktop.NetworkManager</literal>
-      interface deprecated in version 0.7 have been removed.  All the
-      replacement methods and signals have existed since version 0.7 and so are
-      not new to this version of NetworkManager, but some older programs may
-      be using removed items.  The following table lists the removed items and
-      their replacements:
-      <table>
-        <tgroup cols="2">
-          <thead>
-            <row><entry>Removed Item</entry><entry>Replacement</entry></row>
-          </thead>
-          <tbody>
-            <row>
-              <entry><screen>StateChange signal</screen></entry>
-              <entry>
-                Use the <literal>StateChanged</literal> signal, which has the
-                same arguments.
-              </entry>
-            </row>
-            <row>
-              <entry><screen>sleep() and wake() methods</screen></entry>
-              <entry>
-                Use the <literal>Sleep()</literal> method instead, which takes
-                a boolean argument indicating whether NetworkManager should
-                go to sleep or wake up.
-              </entry>
-            </row>
-          </tbody>
-        </tgroup>
-      </table>
-    </para>
-    <para>
-      <emphasis role="strong">Action:</emphasis> update code to use these
-      replacement methods and properties where it used old deprecated ones
-    </para>
-    </section>
-
-  </section>
-
-</chapter>