1/*
2** Copyright 2007, 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.internal.telephony;
18
19import com.android.internal.telephony.uicc.AdnRecord;
20
21
22
23/** Interface for applications to access the ICC phone book.
24 *
25 * <p>The following code snippet demonstrates a static method to
26 * retrieve the IIccPhoneBook interface from Android:</p>
27 * <pre>private static IIccPhoneBook getSimPhoneBookInterface()
28            throws DeadObjectException {
29    IServiceManager sm = ServiceManagerNative.getDefault();
30    IIccPhoneBook spb;
31    spb = IIccPhoneBook.Stub.asInterface(sm.getService("iccphonebook"));
32    return spb;
33}
34 * </pre>
35 */
36
37interface IIccPhoneBook {
38
39    /**
40     * Loads the AdnRecords in efid and returns them as a
41     * List of AdnRecords
42     *
43     * @param efid the EF id of a ADN-like SIM
44     * @return List of AdnRecord
45     */
46    List<AdnRecord> getAdnRecordsInEf(int efid);
47
48    /**
49     * Loads the AdnRecords in efid and returns them as a
50     * List of AdnRecords
51     *
52     * @param efid the EF id of a ADN-like SIM
53     * @param subId user preferred subId
54     * @return List of AdnRecord
55     */
56    List<AdnRecord> getAdnRecordsInEfForSubscriber(long subId, int efid);
57
58    /**
59     * Replace oldAdn with newAdn in ADN-like record in EF
60     *
61     * getAdnRecordsInEf must be called at least once before this function,
62     * otherwise an error will be returned
63     *
64     * @param efid must be one among EF_ADN, EF_FDN, and EF_SDN
65     * @param oldTag adn tag to be replaced
66     * @param oldPhoneNumber adn number to be replaced
67     *        Set both oldTag and oldPhoneNubmer to "" means to replace an
68     *        empty record, aka, insert new record
69     * @param newTag adn tag to be stored
70     * @param newPhoneNumber adn number ot be stored
71     *        Set both newTag and newPhoneNubmer to "" means to replace the old
72     *        record with empty one, aka, delete old record
73     * @param pin2 required to update EF_FDN, otherwise must be null
74     * @return true for success
75     */
76    boolean updateAdnRecordsInEfBySearch(int efid,
77            String oldTag, String oldPhoneNumber,
78            String newTag, String newPhoneNumber,
79            String pin2);
80
81
82
83    /**
84     * Replace oldAdn with newAdn in ADN-like record in EF
85     *
86     * getAdnRecordsInEf must be called at least once before this function,
87     * otherwise an error will be returned
88     *
89     * @param efid must be one among EF_ADN, EF_FDN, and EF_SDN
90     * @param oldTag adn tag to be replaced
91     * @param oldPhoneNumber adn number to be replaced
92     *        Set both oldTag and oldPhoneNubmer to "" means to replace an
93     *        empty record, aka, insert new record
94     * @param newTag adn tag to be stored
95     * @param newPhoneNumber adn number ot be stored
96     *        Set both newTag and newPhoneNubmer to "" means to replace the old
97     *        record with empty one, aka, delete old record
98     * @param pin2 required to update EF_FDN, otherwise must be null
99     * @param subId user preferred subId
100     * @return true for success
101     */
102    boolean updateAdnRecordsInEfBySearchForSubscriber(long subId, int efid,
103            String oldTag, String oldPhoneNumber,
104            String newTag, String newPhoneNumber,
105            String pin2);
106    /**
107     * Update an ADN-like EF record by record index
108     *
109     * This is useful for iteration the whole ADN file, such as write the whole
110     * phone book or erase/format the whole phonebook
111     *
112     * @param efid must be one among EF_ADN, EF_FDN, and EF_SDN
113     * @param newTag adn tag to be stored
114     * @param newPhoneNumber adn number to be stored
115     *        Set both newTag and newPhoneNubmer to "" means to replace the old
116     *        record with empty one, aka, delete old record
117     * @param index is 1-based adn record index to be updated
118     * @param pin2 required to update EF_FDN, otherwise must be null
119     * @return true for success
120     */
121    boolean updateAdnRecordsInEfByIndex(int efid, String newTag,
122            String newPhoneNumber, int index,
123            String pin2);
124
125    /**
126     * Update an ADN-like EF record by record index
127     *
128     * This is useful for iteration the whole ADN file, such as write the whole
129     * phone book or erase/format the whole phonebook
130     *
131     * @param efid must be one among EF_ADN, EF_FDN, and EF_SDN
132     * @param newTag adn tag to be stored
133     * @param newPhoneNumber adn number to be stored
134     *        Set both newTag and newPhoneNubmer to "" means to replace the old
135     *        record with empty one, aka, delete old record
136     * @param index is 1-based adn record index to be updated
137     * @param pin2 required to update EF_FDN, otherwise must be null
138     * @param subId user preferred subId
139     * @return true for success
140     */
141    boolean updateAdnRecordsInEfByIndexForSubscriber(long subId, int efid, String newTag,
142            String newPhoneNumber, int index,
143            String pin2);
144
145    /**
146     * Get the max munber of records in efid
147     *
148     * @param efid the EF id of a ADN-like SIM
149     * @return  int[3] array
150     *            recordSizes[0]  is the single record length
151     *            recordSizes[1]  is the total length of the EF file
152     *            recordSizes[2]  is the number of records in the EF file
153     */
154    int[] getAdnRecordsSize(int efid);
155
156    /**
157     * Get the max munber of records in efid
158     *
159     * @param efid the EF id of a ADN-like SIM
160     * @param subId user preferred subId
161     * @return  int[3] array
162     *            recordSizes[0]  is the single record length
163     *            recordSizes[1]  is the total length of the EF file
164     *            recordSizes[2]  is the number of records in the EF file
165     */
166    int[] getAdnRecordsSizeForSubscriber(long subId, int efid);
167
168}
169