org.opensuse.Agama.Questions1.doc.xml

<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>
  <!--
      org.opensuse.Agama.Questions1:

Agama offers a mechanism to communicate with clients. The D-Bus service exports a *Questions*
object that implements the *org.freedesktop.DBus.ObjectManager* interface. Individual questions are
dynamically exported in a tree under the */org/opensuse/Agama/Questions1* path, for example:

~~~
/org/opensuse/Agama/Questions1
  /org/opensuse/Agama/Questions1/1
  /org/opensuse/Agama/Questions1/2
  /org/opensuse/Agama/Questions1/4
~~~

Each D-Bus question implements its own set of interfaces, depending on the type of question. For
example, a generic question implements *org.opensuse.Agama.Question1*. And a question asking
for the activation of a LUKS device also implements *org.opensuse.Agama.Questions1.WithPassword*.
Questions can be "unexported" from the ObjectManager tree. The service typically unexports a question
when the question is answered and the answer is successfully read.
  -->
  <interface name="org.opensuse.Agama.Questions1">
    <!--
      New:
      @class: string identifier of the same questions. Useful to identify
              similar questions asked multiple times or for matching
              in automatic answers.
      @text: human string with question text
      @options: list of possible options that can be used as answer. Example
                is "OK", "Cancel".
      @default_option: safe default answer that is used e.g. for focus in UI
                       or by non-interactive answering. It has to be included
                       in options parameter.
      @data: additional data that is specific to given question class. Can be
             used for additional details about question that helps with UI
             or with matching automatic answers.

      Creates new generic question.
      Returns the object path of the created question.

    -->
    <method name="New">
      <arg name="class" direction="in" type="s"/>
      <arg name="text" direction="in" type="s"/>
      <arg name="options" direction="in" type="as"/>
      <arg name="default_option" direction="in" type="s"/>
      <arg name="data" direction="in" type="a{ss}"/>
      <arg direction="out" type="o"/>
    </method>

    <!--
      NewWithPassword:
      @class: string identifier of the same questions. Useful to identify
              similar questions asked multiple times or for matching
              in automatic answers.
      @text: human string with question text
      @options: list of possible options that can be used as answer. Example
                is "OK", "Cancel".
      @default_option: safe default answer that is used e.g. for focus in UI
                       or by non-interactive answering. It has to be included
                       in options parameter.
      @data: additional data that is specific to given question class. Can be
             used for additional details about question that helps with UI
             or with matching automatic answers.

      Creates new question with generic base and additional WithPassword interface.
      Returns the object path of the created question.
    -->
    <method name="NewWithPassword">
      <arg name="class" direction="in" type="s"/>
      <arg name="text" direction="in" type="s"/>
      <arg name="options" direction="in" type="as"/>
      <arg name="default_option" direction="in" type="s"/>
      <arg name="data" direction="in" type="a{ss}"/>
      <arg direction="out" type="o"/>
    </method>
    <!--
      Delete:
      @question: object path of question that should be deleted.

      Deletes question. Useful when question is answered and service that asks
      already read answer. Usually called by the one that previously created it.
    -->
    <method name="Delete">
      <arg name="question" type="o" direction="in"/>
    </method>
    <!--
      AddAnswerFile:
      @path: Local fs path to answers file in yaml format.

      Adds file with list of predefined answers that will be used to
      automatically answer matching questions.
    -->
    <method name="AddAnswerFile">
      <arg name="path" type="s" direction="in"/>
    </method>
    <!--
     property that defines if questions is interactive or automatically answered with
     default answer
     -->
    <property name="Interactive" type="b" access="readwrite"/>
  </interface>
</node>