1 /* 2 * Copyright (C) 2011 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 17 package com.example.android.voicemail.common.core; 18 19 import android.provider.VoicemailContract; 20 21 import android.net.Uri; 22 23 import java.io.IOException; 24 import java.io.InputStream; 25 import java.util.List; 26 27 /** 28 * Provides a simple interface to manipulate voicemails within the voicemail content provider. 29 * <p> 30 * Methods on this interface throw checked exceptions only where the corresponding underlying 31 * methods perform an operation that itself requires a checked exception. In all other cases a 32 * {@link RuntimeException} will be thrown here. 33 * <p> 34 * These methods are blocking, and will return control to the caller only when the operation 35 * completes. You should not call any of these methods from your main ui thread, as this may result 36 * in your application becoming unresponsive. 37 */ 38 public interface VoicemailProviderHelper { 39 40 /** Sort order to return results by. */ 41 public enum SortOrder { 42 ASCENDING, 43 DESCENDING, 44 /** Default sort order returned by DB. (Typically Ascending, but no guarantees made). */ 45 DEFAULT 46 } 47 48 /** 49 * Clears all voicemails accessible to this voicemail content provider. 50 * 51 * @return the number of voicemails deleted 52 */ deleteAll()53 public int deleteAll(); 54 55 /** 56 * Inserts a new voicemail into the voicemail content provider. 57 * 58 * @param voicemail data to be inserted 59 * @return {@link Uri} of the newly inserted {@link Voicemail} 60 * @throws IllegalArgumentException if any of the following are true: 61 * <ul> 62 * <li>your voicemail is missing a timestamp</li> 63 * <li>your voiceamil is missing a number</li> 64 * <li>your voicemail is missing the provider id field</li> 65 * <li>voicemail has an id (which would indicate that it has already been inserted) 66 * </li> 67 * </ul> 68 */ insert(Voicemail voicemail)69 public Uri insert(Voicemail voicemail); 70 71 /** 72 * Returns the {@link Voicemail} whose provider data matches the given value. 73 * <p> 74 * It is expected that there be one such voicemail. Returns null if no such voicemail exists, 75 * and returns one chosen arbitrarily if more than one exists. 76 */ findVoicemailBySourceData(String providerData)77 public Voicemail findVoicemailBySourceData(String providerData); 78 79 /** 80 * Returns the {@link Voicemail} corresponding to a given Uri. The uri must correspond to a 81 * unique voicemail record. 82 * <p> 83 * Returns null if no voicemail was found that exactly matched the given uri. 84 */ findVoicemailByUri(Uri uri)85 public Voicemail findVoicemailByUri(Uri uri); 86 87 /** 88 * Updates an existing voicemail in the content provider. 89 * <p> 90 * Note that <b>only the fields that are set</b> on the {@link Voicemail} that you provide will 91 * be used to perform the update. The remaining fields will be left unmodified. To mark a 92 * voicemail as read, create a new {@link Voicemail} that is marked as read, and call update. 93 * 94 * @throws IllegalArgumentException if you provide a {@link Voicemail} that already has a Uri 95 * set, because we don't support altering the Uri of a voicemail, and this most 96 * likely implies that you're using this api incorrectly 97 * @return the number of rows that were updated 98 */ update(Uri uri, Voicemail voicemail)99 public int update(Uri uri, Voicemail voicemail); 100 101 /** 102 * Sets the voicemail content from the supplied input stream. 103 * <p> 104 * The inputStream is owned by the caller and must be closed by it as usual after the call has 105 * returned. 106 * 107 * @throws IOException if there is a problem creating the file or no voicemail is found matching 108 * the given Uri 109 */ setVoicemailContent(Uri voicemailUri, InputStream inputStream, String mimeType)110 public void setVoicemailContent(Uri voicemailUri, InputStream inputStream, String mimeType) 111 throws IOException; 112 113 /** 114 * Sets the voicemail content from the supplied byte array. 115 * 116 * @throws IOException if there is a problem creating the file or no voicemail is found matching 117 * the given Uri 118 */ setVoicemailContent(Uri voicemailUri, byte[] inputBytes, String mimeType)119 public void setVoicemailContent(Uri voicemailUri, byte[] inputBytes, String mimeType) 120 throws IOException; 121 122 /** 123 * Fetch all the voicemails accessible to this voicemail content provider. 124 * 125 * @return the list of voicemails, no guarantee is made about the ordering 126 */ getAllVoicemails()127 public List<Voicemail> getAllVoicemails(); 128 129 /** 130 * Same as {@link #getAllVoicemails()} but also sorts them by the requested column and allows to 131 * set a filter. 132 * 133 * @param filter The filter to apply while retrieving voicemails. 134 * @param sortColumn The column to sort by. Must be one of the values defined in 135 * {@link VoicemailContract.Voicemails}. 136 * @param sortOrder Order to sort by 137 * @return the list of voicemails, sorted by the requested DB column in specified sort order. 138 */ getAllVoicemails(VoicemailFilter filter, String sortColumn, SortOrder sortOrder)139 public List<Voicemail> getAllVoicemails(VoicemailFilter filter, 140 String sortColumn, SortOrder sortOrder); 141 142 /** 143 * Returns the Uri for the voicemail with the specified message Id. 144 */ getUriForVoicemailWithId(long id)145 public Uri getUriForVoicemailWithId(long id); 146 } 147