1/*
2 * Copyright (C) 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.android.omadm.plugin;
18
19import com.android.omadm.plugin.DmtData;
20import com.android.omadm.plugin.DmtPluginNode;
21
22interface IDmtPlugin
23{
24    /**
25     * Initializes the plug-in.
26     *
27     * @param rootPath the root path of the plug-in.
28     * @param parameters initial parameters of the plug-in. Type of the parameter is Map<String, String> type.
29     * @return true in success case, otherwise false.
30     */
31    boolean init(String rootPath, in Map parameters);
32
33    /**
34     * This method returns result of the last operation which has requested by DM engine.
35     * It is required because each plug-in is a content provider and it is impossible to
36     * throw the DmtException with an error code to the DM engine.
37     *
38     * @return operation result of the last operation.
39     */
40    int getOperationResult();
41
42    /**
43     * Sets Server ID of the plug-in.
44     *
45     * @param serverID service ID
46     */
47    void setServerID(String serverID);
48
49    /**
50     * Returns Server ID.
51     *
52     * @return Server ID which has been set by DM engine for the plug-in.
53     */
54    String getServerID();
55
56    /**
57     * The method is called to release plug-in resource when the plug-in is no longer used.
58     *
59     * @return true in success case, otherwise false.
60     */
61    boolean release();
62
63    /**
64     * Gets node by given path.
65     *
66     * If plug-in cannot return the node null value shall be returned by
67     * the method and DM engine will use the getOperationResult() method
68     * to get result of the operation.
69     *
70     * @param path full path to the node.
71     * @return node object in success case, otherwise null.
72     */
73    DmtPluginNode getNode(String path);
74
75    /**
76     * Gets node value by given path.
77     *
78     * If plug-in cannot return the value null value shall be returned by
79     * the method and DM engine will use the getOperationResult() method
80     * to get result of the operation.
81     *
82     * @param path full path to the node.
83     * @return node value object in success case, otherwise null.
84     */
85    DmtData getNodeValue(String path);
86
87    /**
88     * Gets a set of nodes by given path.
89     *
90     * If plug-in cannot return the set null value shall be returned by
91     * the method and DM engine will use the getOperationResult() method
92     * to get result of the operation.
93     *
94     * @param path full path to the node.
95     * @return a set of nodes in success case otherwise null.
96     *         Type of returned value shall be Map<String, DmtPluginNode>.
97     *         Where the first parameter is full path to the node and the
98     *         second is node object.
99     */
100    Map getNodes(String path);
101
102    /**
103     * Creates an interior node in the tree by given path.
104     *
105     * @param path full path to the node.
106     * @return ErrorCodes.SYNCML_DM_SUCCESS in success case, otherwise an error.
107     */
108    int createInteriorNode(String path);
109
110    /**
111     * Creates a leaf node in the tree by given path.
112     *
113     * @param path full path to the node.
114     * @return ErrorCodes.SYNCML_DM_SUCCESS in success case, otherwise an error.
115     */
116    int createLeafNode(String path, in DmtData value);
117
118    /**
119     * Creates a sibling of the node specified by its URI "path".
120     * This new node's name is user-specified as "newNodename".
121     * An error shall be returned in following cases:
122     *   -  If either path or new node name are null
123     *   -  If node to be copied does not exist
124     *   -  If a sibling node with the user-specified name already exists
125     *   -  If the new node cannot be created for some other reason
126     *
127     * NOTE: This is optional command of OMA DM protocol.
128     *       Currently java plug-ins do not support the command.
129     *
130     * @param path full path to node to be cloned.
131     * @param newNodename New node name as specified by user.
132     * @return ErrorCodes.SYNCML_DM_SUCCESS in success case, otherwise an error.
133     */
134    int clone(String path, String newNodename);
135
136    /**
137     * Renames a node.
138     *
139     * NOTE: This is optional command of OMA DM protocol.
140     *       Currently java plug-ins do not support the command.
141     *
142     * @param path full path to node to be renamed.
143     * @param newName new node name.
144     * @return ErrorCodes.SYNCML_DM_SUCCESS in success case, otherwise an error.
145     */
146    int renameNode(String path, String newName);
147
148    /**
149     * Updates a leaf node value by given path.
150     *
151     * @param path full path to the leaf node.
152     * @param newValue new value of the leaf node.
153     * @return ErrorCodes.SYNCML_DM_SUCCESS in success case, otherwise an error.
154     */
155    int updateLeafNode(String path, in DmtData newValue);
156
157    /**
158     * Deletes a node by given path.
159     * @param path full path to the leaf node.
160     * @return ErrorCodes.SYNCML_DM_SUCCESS in success case, otherwise an error.
161     */
162    int deleteNode(String path);
163
164    /**
165     * Performs "Execute" command on a plug-in node.
166     *
167  	 * @param path node path
168     * @param args exec plug-in arguments
169     * @param correlator correlator
170     * @return ErrorCodes.SYNCML_DM_SUCCESS in success case, otherwise an error.
171     */
172    int exec(String path, String args, String correlator);
173
174    /**
175     * Performs commit operation under current DMT.
176     *
177     * @return ErrorCodes.SYNCML_DM_SUCCESS in success case, otherwise an error.
178     */
179    int commit();
180
181    /**
182     * Returns DM account server PW. This is not lookup from the DM tree; this function generates it.
183     *
184     * @return String. null if plugin is not carrier specific
185     */
186    String getServerPW(String aiServerPW);
187
188    /**
189     * Returns DM account client PW. This is not lookup from the DM tree; this function generates it.
190     *
191     * @return String. null if plugin is not carrier specific
192     */
193    String getClientPW(String aiClientPW);
194
195    /**
196     * Returns DM account user name. This is not lookup from the DM tree; this function generates it.
197     *
198     * @return String. null if plugin is not carrier specific
199     */
200    String getUsername(String aiUsername);
201}
202