| /* |
| * Copyright (C) 2011 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package com.example.android.voicemail.common.core; |
| |
| import android.provider.VoicemailContract; |
| |
| import android.net.Uri; |
| |
| import java.io.IOException; |
| import java.io.InputStream; |
| import java.util.List; |
| |
| /** |
| * Provides a simple interface to manipulate voicemails within the voicemail content provider. |
| * <p> |
| * Methods on this interface throw checked exceptions only where the corresponding underlying |
| * methods perform an operation that itself requires a checked exception. In all other cases a |
| * {@link RuntimeException} will be thrown here. |
| * <p> |
| * These methods are blocking, and will return control to the caller only when the operation |
| * completes. You should not call any of these methods from your main ui thread, as this may result |
| * in your application becoming unresponsive. |
| */ |
| public interface VoicemailProviderHelper { |
| |
| /** Sort order to return results by. */ |
| public enum SortOrder { |
| ASCENDING, |
| DESCENDING, |
| /** Default sort order returned by DB. (Typically Ascending, but no guarantees made). */ |
| DEFAULT |
| } |
| |
| /** |
| * Clears all voicemails accessible to this voicemail content provider. |
| * |
| * @return the number of voicemails deleted |
| */ |
| public int deleteAll(); |
| |
| /** |
| * Inserts a new voicemail into the voicemail content provider. |
| * |
| * @param voicemail data to be inserted |
| * @return {@link Uri} of the newly inserted {@link Voicemail} |
| * @throws IllegalArgumentException if any of the following are true: |
| * <ul> |
| * <li>your voicemail is missing a timestamp</li> |
| * <li>your voiceamil is missing a number</li> |
| * <li>your voicemail is missing the provider id field</li> |
| * <li>voicemail has an id (which would indicate that it has already been inserted) |
| * </li> |
| * </ul> |
| */ |
| public Uri insert(Voicemail voicemail); |
| |
| /** |
| * Returns the {@link Voicemail} whose provider data matches the given value. |
| * <p> |
| * It is expected that there be one such voicemail. Returns null if no such voicemail exists, |
| * and returns one chosen arbitrarily if more than one exists. |
| */ |
| public Voicemail findVoicemailBySourceData(String providerData); |
| |
| /** |
| * Returns the {@link Voicemail} corresponding to a given Uri. The uri must correspond to a |
| * unique voicemail record. |
| * <p> |
| * Returns null if no voicemail was found that exactly matched the given uri. |
| */ |
| public Voicemail findVoicemailByUri(Uri uri); |
| |
| /** |
| * Updates an existing voicemail in the content provider. |
| * <p> |
| * Note that <b>only the fields that are set</b> on the {@link Voicemail} that you provide will |
| * be used to perform the update. The remaining fields will be left unmodified. To mark a |
| * voicemail as read, create a new {@link Voicemail} that is marked as read, and call update. |
| * |
| * @throws IllegalArgumentException if you provide a {@link Voicemail} that already has a Uri |
| * set, because we don't support altering the Uri of a voicemail, and this most |
| * likely implies that you're using this api incorrectly |
| * @return the number of rows that were updated |
| */ |
| public int update(Uri uri, Voicemail voicemail); |
| |
| /** |
| * Sets the voicemail content from the supplied input stream. |
| * <p> |
| * The inputStream is owned by the caller and must be closed by it as usual after the call has |
| * returned. |
| * |
| * @throws IOException if there is a problem creating the file or no voicemail is found matching |
| * the given Uri |
| */ |
| public void setVoicemailContent(Uri voicemailUri, InputStream inputStream, String mimeType) |
| throws IOException; |
| |
| /** |
| * Sets the voicemail content from the supplied byte array. |
| * |
| * @throws IOException if there is a problem creating the file or no voicemail is found matching |
| * the given Uri |
| */ |
| public void setVoicemailContent(Uri voicemailUri, byte[] inputBytes, String mimeType) |
| throws IOException; |
| |
| /** |
| * Fetch all the voicemails accessible to this voicemail content provider. |
| * |
| * @return the list of voicemails, no guarantee is made about the ordering |
| */ |
| public List<Voicemail> getAllVoicemails(); |
| |
| /** |
| * Same as {@link #getAllVoicemails()} but also sorts them by the requested column and allows to |
| * set a filter. |
| * |
| * @param filter The filter to apply while retrieving voicemails. |
| * @param sortColumn The column to sort by. Must be one of the values defined in |
| * {@link VoicemailContract.Voicemails}. |
| * @param sortOrder Order to sort by |
| * @return the list of voicemails, sorted by the requested DB column in specified sort order. |
| */ |
| public List<Voicemail> getAllVoicemails(VoicemailFilter filter, |
| String sortColumn, SortOrder sortOrder); |
| |
| /** |
| * Returns the Uri for the voicemail with the specified message Id. |
| */ |
| public Uri getUriForVoicemailWithId(long id); |
| } |