1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
|
/*
* Copyright (c) 2017 - 2019, SmartDeviceLink Consortium, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* Redistributions of source code must retain the above copyright notice, this
* list of conditions and the following disclaimer.
*
* Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following
* disclaimer in the documentation and/or other materials provided with the
* distribution.
*
* Neither the name of the SmartDeviceLink Consortium, Inc. nor the names of its
* contributors may be used to endorse or promote products derived from this
* software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
package com.smartdevicelink.proxy.rpc;
import androidx.annotation.NonNull;
import com.smartdevicelink.protocol.enums.FunctionID;
import com.smartdevicelink.proxy.RPCRequest;
import java.util.Hashtable;
import java.util.List;
/**
* <p>This class will add a command to the application's Command Menu</p>
*
*
* <p><b>Note:</b> A command will be added to the end of the list of elements in
* the Command Menu under the following conditions:</p>
*
* <ul>
* <li>When a Command is added with no MenuParams value provided</li>
* <li>When a MenuParams value is provided with a MenuParam.position value
* greater than or equal to the number of menu items currently defined in the
* menu specified by the MenuParam.parentID value</li>
* </ul>
*
*
* <p>The set of choices which the application builds using AddCommand can be a
* mixture of:</p>
*
* <ul>
* <li>Choices having only VR synonym definitions, but no MenuParams definitions
* </li>
* <li>Choices having only MenuParams definitions, but no VR synonym definitions
* </li>
* <li>Choices having both MenuParams and VR synonym definitions</li>
* </ul>
*
* <p><b>HMILevel needs to be FULL, LIMITED or BACKGROUND</b></p>
*
* <p><b>Parameter List</b></p>
* <table border="1" rules="all">
* <tr>
* <th>Param Name</th>
* <th>Type</th>
* <th>Description</th>
* <th> Req.</th>
* <th>Notes</th>
* <th>Version Available</th>
* </tr>
* <tr>
* <td>cmdID</td>
* <td> Integer</td>
* <td>unique ID of the command to add</td>
* <td>Y</td>
* <td> minvalue:0; maxvalue:2000000000</td>
* <td>SmartDeviceLink 1.0</td>
* <tr>
* <td>menuParams</td>
* <td>ButtonName</td>
* <td>Name of the button to unsubscribe.</td>
* <td>Y</td>
* <td></td>
* <td>SmartDeviceLink 1.0</td>
* </tr>
* <tr>
* <td>vrCommands</td>
* <td>String</td>
* <td><p>An array of strings to be used as VR synonyms for this command.</p> <p>If this array is provided, it may not be empty.</p></td>
* <td>N</td>
* <td>minsize:1; maxsize:100</td>
* <td>SmartDeviceLink 1.0</td>
* <tr>
* <td>cmdIcon</td>
* <td>Image</td>
* <td><p>Image struct determining whether static or dynamic icon.</p><p>If omitted on supported displays, no (or the default if applicable) icon shall be displayed.</p></td>
* <td>N</td>
* <td></td>
* <td>SmartDeviceLink 1.0</td>
* </tr>
* <tr>
* <td>secondaryImage</td>
* <td>Image</td>
* <td>Optional secondary image struct for menu cell</td>
* <td>N</td>
* <td></td>
* <td>SmartDeviceLink 7.1.0</td>
* </tr>
* </table>
* <p> <b>Response</b></p><p>Indicates that the corresponding request has failed or succeeded, if the response returns with a SUCCESS result code, this means a command was added to the Command Menu successfully.</p>
*
* <p><b>Non-default Result Codes:</b></p> <p>INVALID_ID</p> <p>DUPLICATE_NAME</p>
*
* @see DeleteCommand
* @see AddSubMenu
* @see DeleteSubMenu
* @since SmartDeviceLink 1.0
*/
public class AddCommand extends RPCRequest {
public static final String KEY_CMD_ICON = "cmdIcon";
public static final String KEY_MENU_PARAMS = "menuParams";
public static final String KEY_CMD_ID = "cmdID";
public static final String KEY_VR_COMMANDS = "vrCommands";
public static final String KEY_SECONDARY_IMAGE = "secondaryImage";
/**
* Constructs a new AddCommand object
*/
public AddCommand() {
super(FunctionID.ADD_COMMAND.toString());
}
/**
* <p>
* Constructs a new AddCommand object indicated by the Hashtable
* parameter
* </p>
*
* @param hash The Hashtable to use
*/
public AddCommand(Hashtable<String, Object> hash) {
super(hash);
}
/**
* Constructs a new AddCommand object
*
* @param cmdID an integer object representing a Command ID <p><b>Notes:</b> Min Value: 0; Max Value: 2000000000</p>
*/
public AddCommand(@NonNull Integer cmdID) {
this();
setCmdID(cmdID);
}
/**
* <p>
* Returns an <i>Integer</i> object representing the Command ID that you want to add
* </p>
*
* @return Integer -an integer representation a Unique Command ID
*/
public Integer getCmdID() {
return getInteger(KEY_CMD_ID);
}
/**
* <p>Sets a Unique Command ID that identifies the command. Is returned in an
* <i>{@linkplain OnCommand}</i> notification to identify the command
* selected by the user</p>
*
* @param cmdID an integer object representing a Command ID
* <p>
* <b>Notes:</b> Min Value: 0; Max Value: 2000000000</p>
*/
public AddCommand setCmdID(@NonNull Integer cmdID) {
setParameters(KEY_CMD_ID, cmdID);
return this;
}
/**
* <p>
* Returns a <I>MenuParams</I> object which will defined the command and how
* it is added to the Command Menu
* </p>
*
* @return MenuParams -a MenuParams object
*/
public MenuParams getMenuParams() {
return (MenuParams) getObject(MenuParams.class, KEY_MENU_PARAMS);
}
/**
* <p>
* Sets Menu parameters</p>
* If provided, this will define the command and how it is added to the
* Command Menu<p>
* If null, commands will not be accessible through the HMI application menu
* </p>
*
* @param menuParams a menuParams object
*/
public AddCommand setMenuParams(MenuParams menuParams) {
setParameters(KEY_MENU_PARAMS, menuParams);
return this;
}
/**
* <p>
* Gets Voice Recognition Commands
* </p>
*
* @return List<String> -(List<String>) indicating one or more VR phrases
*/
@SuppressWarnings("unchecked")
public List<String> getVrCommands() {
return (List<String>) getObject(String.class, KEY_VR_COMMANDS);
}
/**
* <p>
* Sets Voice Recognition Commands </p>
* <p>If provided, defines one or more VR phrases the recognition of any of
* which triggers the <i>{@linkplain OnCommand}</i> notification with this
* cmdID</p>
* <p>If null, commands will not be accessible by voice commands (when the user
* hits push-to-talk)
* </p>
*
* @param vrCommands List<String> indicating one or more VR phrases
* <p>
* <b>Notes: </b>Optional only if menuParams is provided. If
* provided, array must contain at least one non-empty (not null,
* not zero-length, not whitespace only) element</p>
*/
public AddCommand setVrCommands(List<String> vrCommands) {
setParameters(KEY_VR_COMMANDS, vrCommands);
return this;
}
/**
* <p>Gets the image to be shown along with a command </p>
*
* @return Image -an Image object
* @since SmartDeviceLink 2.0
*/
public Image getCmdIcon() {
return (Image) getObject(Image.class, KEY_CMD_ICON);
}
/**
* <p>Sets the Image
* If provided, defines the image to be be shown along with a command</p>
*
* @param cmdIcon <p>an Image obj representing the Image obj shown along with a
* command</p>
* <p>
* <b>Notes: </b>If omitted on supported displays, no (or the
* default if applicable) icon will be displayed</p>
* @since SmartDeviceLink 2.0
*/
public AddCommand setCmdIcon(Image cmdIcon) {
setParameters(KEY_CMD_ICON, cmdIcon);
return this;
}
/**
* Sets the secondaryImage.
*
* @param secondaryImage Optional secondary image struct for menu cell
* @since SmartDeviceLink 7.1.0
*/
public AddCommand setSecondaryImage(Image secondaryImage) {
setParameters(KEY_SECONDARY_IMAGE, secondaryImage);
return this;
}
/**
* Gets the secondaryImage.
*
* @return Image Optional secondary image struct for menu cell
* @since SmartDeviceLink 7.1.0
*/
public Image getSecondaryImage() {
return (Image) getObject(Image.class, KEY_SECONDARY_IMAGE);
}
}
|
