1 <listitem id="command_version">
4 <parameter>number</parameter>
7 This exchanges with the frontend the protocol version
8 number that is being used. The current version is
9 2.1. Versions in the 2.x series will be
10 backwards-compatible. You may specify the protocol version
11 number you are speaking. The frontend will return the version
12 of the protocol it speaks. If the version you specify is too
13 low, this command will return the numeric return code
14 <literal>30</literal>.
17 <listitem id="command_capb">
20 <parameter>capabilities</parameter>
23 This exchanges with the frontend a list of supported capabilities
24 Capabilities both the frontend and your confmodule support may be
25 used; the capabilities supported by the frontend are returned by
28 <title>Currently used capabilities</title>
32 <entry>capability</entry>
33 <entry>description</entry>
40 Backing up to a previous step is supported.
46 The frontend expects commands sent to it to have backslashes and
47 newlines quoted as <literal>\\</literal> and <literal>\n</literal>
48 respectively and will in turn quote backslashes and newlines in its
49 replies. See <citerefentry><refentrytitle>debconf-escape</refentrytitle>
50 <manvolnum>1</manvolnum></citerefentry>.
54 <entry>multiselect</entry>
56 The multiselect data type is supported. You do not need to
57 check this capability if you depend on any modern version
66 <listitem id="command_settitle">
69 <parameter>template</parameter>
72 You can use this command to set a title in the
73 frontend. This may appear in different ways, depending on the
74 frontend being used, for example it might change the title
75 of the frontend's window. If you don't specify anything, a
76 title will automatically be generated.
79 Using a template has the advantage that titles are translatable
80 and that they can be maintained in the same place as other text
84 <listitem id="command_title">
87 <parameter>string</parameter>
90 Similar to SETTITLE, but takes a string instead of a template as
91 parameter. Consequence is that the title will not be translatable,
92 unless some other mechanism (like gettext) is used.
95 <listitem id="command_stop">
100 This command tells the frontend you're done talking to it. Typically
101 the frontend can detect the termination of your program and this
102 command is not necessary.
105 <listitem id="command_input">
108 <parameter>priority</parameter>
109 <parameter>question</parameter>
112 This tells the frontend to display a question (or other type of
113 item) to the user. <parameter>question</parameter> is the name of the
114 item to display, all other information about the item is retrieved
115 from the templates described previously.
116 <parameter>priority</parameter> is how important it is that the
117 user be prompted. The frontend need only ask this question if the
118 priority is high enough. The question is not displayed until a go
119 command is given. This allows us to ask multiple questions in a single
120 screen. Once a question has been displayed to the user and the user has
121 provided input, the frontend will set the
122 <literal>seen</literal> flag.
126 Note that the frontend decides if the user is actually
127 prompted or not. If the user has already answered a
128 question, they are normally not asked it again even if
129 input is called again. And if the user is ignoring low
130 priority items, they will not see them. In either of
131 these cases, this command returns the numeric return code
132 <literal>30</literal>.
135 <listitem id="command_beginblock">
140 <listitem id="command_endblock">
145 Some frontends are able to display a number of items to
146 the user at once. To do this, they need to be given blocks
147 of input commands, enclosed in the BEGINBLOCK and ENDBLOCK
148 commands. Blocks can be nested and very advanced frontends
149 may use this as a user interface hint.
153 There is an implicit block around any set of INPUT commands
154 that are not enclosed in an explicit block.
158 <listitem id="command_go">
163 Shows the current set of accumulated items to the user and lets
164 them fill in values, etc. If the backup capability is supported
165 and the user indicates they want to back up a step, this command
166 returns the numeric return code <literal>30</literal>.
169 <listitem id="command_clear">
174 Clears the accumulated set of INPUT commands without displaying
178 <listitem id="command_get">
180 GET <parameter>question</parameter>
183 Ask the frontend to tell you how the user answered a question. The
184 value is returned to you.
187 <listitem id="command_set">
190 <parameter>question</parameter>
191 <parameter>value</parameter>
194 Set the answer of a question to a value.
197 <listitem id="command_reset">
199 RESET <parameter>question</parameter>
202 Reset the question to its default value. This includes
203 resetting flags to their defaults.
206 <listitem id="command_subst">
209 <parameter>question</parameter>
210 <parameter>key</parameter>
211 <parameter>value</parameter>
214 Questions (and other items) can have substitutions embedded in
215 their descriptions (and, currently in their choices fields). These
216 substitutions look like "<literal>${key}</literal>". When the
217 question is displayed, the substitutions are replaced with their
218 values. This command can be used to set the value of a
222 <listitem id="command_fget">
225 <parameter>question</parameter>
226 <parameter>flag</parameter>
229 Questions (and other items) can have flags associated with them. The
230 flags have a value of "<literal>true</literal>" or
231 "<literal>false</literal>". This command returns
235 <listitem id="command_fset">
238 <parameter>question</parameter>
239 <parameter>flag</parameter>
240 <parameter>value</parameter>
243 This sets the state of a flag on a question. Valid
244 states for the flag are "<literal>true</literal>" and
245 "<literal>false</literal>".
248 One common flag is the
249 "<literal>seen</literal>" flag. It is normally only set if
250 a user already seen a question.
251 Typically, frontends only display questions to users if they have the
252 seen flag set to "false". Sometimes you want the user to see a
253 question again -- in these cases you can set the seen flag to
254 false to force the frontend to redisplay it.
257 Note that as a special convenience behavior, frontends will
258 redisplay already seen questions if the question was first seen by
259 the user in the same confmodule run. This makes it easy for a
260 confmodule to back up to previous questions without having to reset
264 <listitem id="command_metaget">
267 <parameter>question</parameter>
268 <parameter>field</parameter>
271 This returns the value of any field of a question (the description, for
275 <listitem id="command_register">
278 <parameter>template</parameter>
279 <parameter>question</parameter>
282 This creates a new question that is bound to a
283 template. By default each template has an associated
284 question with the same name. However, any number of
285 questions can really be associated with a template, and
286 this lets you create more such questions.
289 <listitem id="command_unregister">
292 <parameter>question</parameter>
295 This removes a question from the database.
298 <listitem id="command_purge">
303 Call this in your postrm when your package is
304 purged. It removes all templates and questions your
305 package has generated.