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.internal.telephony;
18
19import android.app.PendingIntent;
20import android.content.ContentValues;
21import android.net.Uri;
22import android.os.Bundle;
23
24/**
25 * Service interface to handle MMS API requests
26 */
27interface IMms {
28    /**
29     * Send an MMS message
30     *
31     * @param subId the SIM id
32     * @param callingPkg the package name of the calling app
33     * @param contentUri the content uri from which to read MMS message encoded in standard MMS
34     *  PDU format
35     * @param locationUrl the optional location url for where this message should be sent to
36     * @param configOverrides the carrier-specific messaging configuration values to override for
37     *  sending the message. See {@link android.telephony.SmsManager} for the value names and types.
38     * @param sentIntent if not NULL this <code>PendingIntent</code> is
39     *  broadcast when the message is successfully sent, or failed
40     */
41    void sendMessage(int subId, String callingPkg, in Uri contentUri,
42            String locationUrl, in Bundle configOverrides, in PendingIntent sentIntent);
43
44    /**
45     * Download an MMS message using known location and transaction id
46     *
47     * @param subId the SIM id
48     * @param callingPkg the package name of the calling app
49     * @param locationUrl the location URL of the MMS message to be downloaded, usually obtained
50     *  from the MMS WAP push notification
51     * @param contentUri a contentUri to which the downloaded MMS message will be written
52     * @param configOverrides the carrier-specific messaging configuration values to override for
53     *  downloading the message. See {@link android.telephony.SmsManager} for the value names and
54     *  types.
55     * @param downloadedIntent if not NULL this <code>PendingIntent</code> is
56     *  broadcast when the message is downloaded, or the download is failed
57     */
58    void downloadMessage(int subId, String callingPkg, String locationUrl,
59            in Uri contentUri, in Bundle configOverrides,
60            in PendingIntent downloadedIntent);
61
62    /**
63     * Get carrier-dependent configuration values.
64     *
65     * @param subId the SIM id
66     */
67    Bundle getCarrierConfigValues(int subId);
68
69    /**
70     * Import a text message into system's SMS store
71     *
72     * @param callingPkg the calling app's package name
73     * @param address the destination address of the message
74     * @param type the type of the message
75     * @param text the message text
76     * @param timestampMillis the message timestamp in milliseconds
77     * @param seen if the message is seen
78     * @param read if the message is read
79     * @return the message URI, null if failed
80     */
81    Uri importTextMessage(String callingPkg, String address, int type, String text,
82            long timestampMillis, boolean seen, boolean read);
83
84    /**
85      * Import a multimedia message into system's MMS store
86      *
87      * @param callingPkg the package name of the calling app
88      * @param contentUri the content uri from which to read PDU of the message to import
89      * @param messageId the optional message id
90      * @param timestampSecs the message timestamp in seconds
91      * @param seen if the message is seen
92      * @param read if the message is read
93      * @return the message URI, null if failed
94      */
95    Uri importMultimediaMessage(String callingPkg, in Uri contentUri, String messageId,
96            long timestampSecs, boolean seen, boolean read);
97
98    /**
99     * Delete a system stored SMS or MMS message
100     *
101     * @param callingPkg the package name of the calling app
102     * @param messageUri the URI of the stored message
103     * @return true if deletion is successful, false otherwise
104     */
105    boolean deleteStoredMessage(String callingPkg, in Uri messageUri);
106
107    /**
108     * Delete a system stored SMS or MMS thread
109     *
110     * @param callingPkg the package name of the calling app
111     * @param conversationId the ID of the message conversation
112     * @return true if deletion is successful, false otherwise
113     */
114    boolean deleteStoredConversation(String callingPkg, long conversationId);
115
116    /**
117     * Update the status properties of a system stored SMS or MMS message, e.g.
118     * the read status of a message, etc.
119     *
120     * @param callingPkg the package name of the calling app
121     * @param messageUri the URI of the stored message
122     * @param statusValues a list of status properties in key-value pairs to update
123     * @return true if deletion is successful, false otherwise
124     */
125    boolean updateStoredMessageStatus(String callingPkg, in Uri messageUri,
126            in ContentValues statusValues);
127
128    /**
129     * Archive or unarchive a stored conversation
130     *
131     * @param callingPkg the package name of the calling app
132     * @param conversationId the ID of the message conversation
133     * @param archived true to archive the conversation, false otherwise
134     * @return true if update is successful, false otherwise
135     */
136    boolean archiveStoredConversation(String callingPkg, long conversationId, boolean archived);
137
138    /**
139     * Add a text message draft to system SMS store
140     *
141     * @param callingPkg the package name of the calling app
142     * @param address the destination address of message
143     * @param text the body of the message to send
144     * @return the URI of the stored draft message
145     */
146    Uri addTextMessageDraft(String callingPkg, String address, String text);
147
148    /**
149     * Add a multimedia message draft to system MMS store
150     *
151     * @param callingPkg the package name of the calling app
152     * @param contentUri the content Uri from which to read PDU data of the draft MMS
153     * @return the URI of the stored draft message
154     */
155    Uri addMultimediaMessageDraft(String callingPkg, in Uri contentUri);
156
157    /**
158     * Send a system stored MMS message
159     *
160     * This is used for sending a previously sent, but failed-to-send, message or
161     * for sending a text message that has been stored as a draft.
162     *
163     * @param subId the SIM id
164     * @param callingPkg the package name of the calling app
165     * @param messageUri the URI of the stored message
166     * @param configOverrides the carrier-specific messaging configuration values to override for
167     *  sending the message. See {@link android.telephony.SmsManager} for the value names and types.
168     * @param sentIntent if not NULL this <code>PendingIntent</code> is
169     *  broadcast when the message is successfully sent, or failed
170     */
171    void sendStoredMessage(int subId, String callingPkg, in Uri messageUri,
172            in Bundle configOverrides, in PendingIntent sentIntent);
173
174    /**
175     * Turns on/off the flag to automatically write sent/received SMS/MMS messages into system
176     *
177     * When this flag is on, all SMS/MMS sent/received are stored by system automatically
178     * When this flag is off, only SMS/MMS sent by non-default SMS apps are stored by system
179     * automatically
180     *
181     * This flag can only be changed by default SMS apps
182     *
183     * @param callingPkg the name of the calling app package
184     * @param enabled Whether to enable message auto persisting
185     */
186    void setAutoPersisting(String callingPkg, boolean enabled);
187
188    /**
189     * Get the value of the flag to automatically write sent/received SMS/MMS messages into system
190     *
191     * When this flag is on, all SMS/MMS sent/received are stored by system automatically
192     * When this flag is off, only SMS/MMS sent by non-default SMS apps are stored by system
193     * automatically
194     *
195     * @return the current value of the auto persist flag
196     */
197    boolean getAutoPersisting();
198}
199