service/carrier/CarrierMessagingService.java

/*
 * Copyright (C) 2014 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 android.service.carrier;

import android.annotation.NonNull;
import android.annotation.Nullable;
import android.annotation.SdkConstant;
import android.app.Service;
import android.content.Intent;
import android.net.Uri;
import android.os.IBinder;
import android.os.RemoteException;

import java.util.List;

/**
 * A service that receives calls from the system when new SMS and MMS are
 * sent or received.
 * <p>To extend this class, you must declare the service in your manifest file with
 * the {@link android.Manifest.permission#BIND_CARRIER_SERVICES} permission
 * and include an intent filter with the {@link #SERVICE_INTERFACE} action. For example:</p>
 * <pre>
 * &lt;service android:name=".MyMessagingService"
 *          android:label="&#64;string/service_name"
 *          android:permission="android.permission.BIND_CARRIER_SERVICES">
 *     &lt;intent-filter>
 *         &lt;action android:name="android.service.carrier.CarrierMessagingService" />
 *     &lt;/intent-filter>
 * &lt;/service></pre>
 */
public abstract class CarrierMessagingService extends Service {
    /**
     * The {@link android.content.Intent} that must be declared as handled by the service.
     */
    @SdkConstant(SdkConstant.SdkConstantType.SERVICE_ACTION)
    public static final String SERVICE_INTERFACE
            = "android.service.carrier.CarrierMessagingService";

    /**
     * The default bitmask value passed to the callback of {@link #onReceiveTextSms} with all
     * {@code RECEIVE_OPTIONS_x} flags cleared to indicate that the message should be kept and a
     * new message notification should be shown.
     *
     * @see #RECEIVE_OPTIONS_DROP
     * @see #RECEIVE_OPTIONS_SKIP_NOTIFY_WHEN_CREDENTIAL_ENCRYPTED_STORAGE_UNAVAILABLE
     */
    public static final int RECEIVE_OPTIONS_DEFAULT = 0;

    /**
     * Used to set the flag in the bitmask passed to the callback of {@link #onReceiveTextSms} to
     * indicate that the inbound SMS should be dropped.
     */
    public static final int RECEIVE_OPTIONS_DROP = 0x1;

    /**
     * Used to set the flag in the bitmask passed to the callback of {@link #onReceiveTextSms} to
     * indicate that a new message notification should not be shown to the user when the
     * credential-encrypted storage of the device is not available before the user unlocks the
     * phone. It is only applicable to devices that support file-based encryption.
     */
    public static final int RECEIVE_OPTIONS_SKIP_NOTIFY_WHEN_CREDENTIAL_ENCRYPTED_STORAGE_UNAVAILABLE = 0x2;

    /**
     * Indicates that an SMS or MMS message was successfully sent.
     */
    public static final int SEND_STATUS_OK = 0;

    /**
     * SMS/MMS sending failed. We should retry via the carrier network.
     */
    public static final int SEND_STATUS_RETRY_ON_CARRIER_NETWORK = 1;

    /**
     * SMS/MMS sending failed. We should not retry via the carrier network.
     */
    public static final int SEND_STATUS_ERROR = 2;

    /**
     * Successfully downloaded an MMS message.
     */
    public static final int DOWNLOAD_STATUS_OK = 0;

    /**
     * MMS downloading failed. We should retry via the carrier network.
     */
    public static final int DOWNLOAD_STATUS_RETRY_ON_CARRIER_NETWORK = 1;

    /**
     * MMS downloading failed. We should not retry via the carrier network.
     */
    public static final int DOWNLOAD_STATUS_ERROR = 2;

    /**
     * Flag to request SMS delivery status report.
     */
    public static final int SEND_FLAG_REQUEST_DELIVERY_STATUS = 1;

    private final ICarrierMessagingWrapper mWrapper = new ICarrierMessagingWrapper();

    /**
     * Override this method to filter inbound SMS messages.
     *
     * @param pdu the PDUs of the message
     * @param format the format of the PDUs, typically "3gpp" or "3gpp2"
     * @param destPort the destination port of a binary SMS, this will be -1 for text SMS
     * @param subId SMS subscription ID of the SIM
     * @param callback result callback. Call with {@code true} to keep an inbound SMS message and
     *        deliver to SMS apps, and {@code false} to drop the message.
     * @deprecated Use {@link #onReceiveTextSms} instead.
     */
    @Deprecated
    public void onFilterSms(@NonNull MessagePdu pdu, @NonNull String format, int destPort,
            int subId, @NonNull ResultCallback<Boolean> callback) {
        // optional
        try {
            callback.onReceiveResult(true);
        } catch (RemoteException ex) {
        }
    }

    /**
     * Override this method to filter inbound SMS messages.
     *
     * <p>This method will be called once for every incoming text SMS. You can invoke the callback
     * with a bitmask to tell the platform how to handle the SMS. For a SMS received on a
     * file-based encryption capable device while the credential-encrypted storage is not available,
     * this method will be called for the second time when the credential-encrypted storage becomes
     * available after the user unlocks the phone, if the bit {@link #RECEIVE_OPTIONS_DROP} is not
     * set when invoking the callback.
     *
     * @param pdu the PDUs of the message
     * @param format the format of the PDUs, typically "3gpp" or "3gpp2"
     * @param destPort the destination port of a binary SMS, this will be -1 for text SMS
     * @param subId SMS subscription ID of the SIM
     * @param callback result callback. Call with a bitmask integer to indicate how the incoming
     *        text SMS should be handled by the platform. Use {@link #RECEIVE_OPTIONS_DROP} and
     *        {@link #RECEIVE_OPTIONS_SKIP_NOTIFY_WHEN_CREDENTIAL_ENCRYPTED_STORAGE_UNAVAILABLE}
     *        to set the flags in the bitmask.
     */
    public void onReceiveTextSms(@NonNull MessagePdu pdu, @NonNull String format,
            int destPort, int subId, @NonNull final ResultCallback<Integer> callback) {
        onFilterSms(pdu, format, destPort, subId, new ResultCallback<Boolean>() {
            @Override
            public void onReceiveResult(Boolean result) throws RemoteException {
                callback.onReceiveResult(result ? RECEIVE_OPTIONS_DEFAULT : RECEIVE_OPTIONS_DROP
                    | RECEIVE_OPTIONS_SKIP_NOTIFY_WHEN_CREDENTIAL_ENCRYPTED_STORAGE_UNAVAILABLE);
            }
        });
    }

    /**
     * Override this method to intercept text SMSs sent from the device.
     * @deprecated Override {@link #onSendTextSms} below instead.
     *
     * @param text the text to send
     * @param subId SMS subscription ID of the SIM
     * @param destAddress phone number of the recipient of the message
     * @param callback result callback. Call with a {@link SendSmsResult}.
     */
    @Deprecated
    public void onSendTextSms(
            @NonNull String text, int subId, @NonNull String destAddress,
            @NonNull ResultCallback<SendSmsResult> callback) {
        // optional
        try {
            callback.onReceiveResult(new SendSmsResult(SEND_STATUS_RETRY_ON_CARRIER_NETWORK, 0));
        } catch (RemoteException ex) {
        }
    }

    /**
     * Override this method to intercept text SMSs sent from the device.
     *
     * @param text the text to send
     * @param subId SMS subscription ID of the SIM
     * @param destAddress phone number of the recipient of the message
     * @param sendSmsFlag Flag for sending SMS. Acceptable values are 0 and
     *        {@link #SEND_FLAG_REQUEST_DELIVERY_STATUS}.
     * @param callback result callback. Call with a {@link SendSmsResult}.
     */
    public void onSendTextSms(
            @NonNull String text, int subId, @NonNull String destAddress,
            int sendSmsFlag, @NonNull ResultCallback<SendSmsResult> callback) {
        // optional
        onSendTextSms(text, subId, destAddress, callback);
    }

    /**
     * Override this method to intercept binary SMSs sent from the device.
     * @deprecated Override {@link #onSendDataSms} below instead.
     *
     * @param data the binary content
     * @param subId SMS subscription ID of the SIM
     * @param destAddress phone number of the recipient of the message
     * @param destPort the destination port
     * @param callback result callback. Call with a {@link SendSmsResult}.
     */
    @Deprecated
    public void onSendDataSms(@NonNull byte[] data, int subId,
            @NonNull String destAddress, int destPort,
            @NonNull ResultCallback<SendSmsResult> callback) {
        // optional
        try {
            callback.onReceiveResult(new SendSmsResult(SEND_STATUS_RETRY_ON_CARRIER_NETWORK, 0));
        } catch (RemoteException ex) {
        }
    }

    /**
     * Override this method to intercept binary SMSs sent from the device.
     *
     * @param data the binary content
     * @param subId SMS subscription ID of the SIM
     * @param destAddress phone number of the recipient of the message
     * @param destPort the destination port
     * @param sendSmsFlag Flag for sending SMS. Acceptable values are 0 and
     *        {@link #SEND_FLAG_REQUEST_DELIVERY_STATUS}.
     * @param callback result callback. Call with a {@link SendSmsResult}.
     */
    public void onSendDataSms(@NonNull byte[] data, int subId,
            @NonNull String destAddress, int destPort, int sendSmsFlag,
            @NonNull ResultCallback<SendSmsResult> callback) {
        // optional
        onSendDataSms(data, subId, destAddress, destPort, callback);
    }

    /**
     * Override this method to intercept long SMSs sent from the device.
     * @deprecated Override {@link #onSendMultipartTextSms} below instead.
     *
     * @param parts a {@link List} of the message parts
     * @param subId SMS subscription ID of the SIM
     * @param destAddress phone number of the recipient of the message
     * @param callback result callback. Call with a {@link SendMultipartSmsResult}.
     */
    @Deprecated
    public void onSendMultipartTextSms(@NonNull List<String> parts,
            int subId, @NonNull String destAddress,
            @NonNull ResultCallback<SendMultipartSmsResult> callback) {
        // optional
        try {
            callback.onReceiveResult(
                    new SendMultipartSmsResult(SEND_STATUS_RETRY_ON_CARRIER_NETWORK, null));
        } catch (RemoteException ex) {
        }
    }

    /**
     * Override this method to intercept long SMSs sent from the device.
     *
     * @param parts a {@link List} of the message parts
     * @param subId SMS subscription ID of the SIM
     * @param destAddress phone number of the recipient of the message
     * @param sendSmsFlag Flag for sending SMS. Acceptable values are 0 and
     *        {@link #SEND_FLAG_REQUEST_DELIVERY_STATUS}.
     * @param callback result callback. Call with a {@link SendMultipartSmsResult}.
     */
    public void onSendMultipartTextSms(@NonNull List<String> parts,
            int subId, @NonNull String destAddress, int sendSmsFlag,
            @NonNull ResultCallback<SendMultipartSmsResult> callback) {
        // optional
        onSendMultipartTextSms(parts, subId, destAddress, callback);
    }

    /**
     * Override this method to intercept MMSs sent from the device.
     *
     * @param pduUri the content provider URI of the PDU to send
     * @param subId SMS subscription ID of the SIM
     * @param location the optional URI to send this MMS PDU. If this is {code null},
     *        the PDU should be sent to the default MMSC URL.
     * @param callback result callback. Call with a {@link SendMmsResult}.
     */
    public void onSendMms(@NonNull Uri pduUri, int subId,
            @Nullable Uri location, @NonNull ResultCallback<SendMmsResult> callback) {
        // optional
        try {
            callback.onReceiveResult(new SendMmsResult(SEND_STATUS_RETRY_ON_CARRIER_NETWORK, null));
        } catch (RemoteException ex) {
        }
    }

    /**
     * Override this method to download MMSs received.
     *
     * @param contentUri the content provider URI of the PDU to be downloaded.
     * @param subId SMS subscription ID of the SIM
     * @param location the URI of the message to be downloaded.
     * @param callback result callback. Call with a status code which is one of
     *        {@link #DOWNLOAD_STATUS_OK},
     *        {@link #DOWNLOAD_STATUS_RETRY_ON_CARRIER_NETWORK}, or {@link #DOWNLOAD_STATUS_ERROR}.
     */
    public void onDownloadMms(@NonNull Uri contentUri, int subId, @NonNull Uri location,
            @NonNull ResultCallback<Integer> callback) {
        // optional
        try {
            callback.onReceiveResult(DOWNLOAD_STATUS_RETRY_ON_CARRIER_NETWORK);
        } catch (RemoteException ex) {
        }
    }

    @Override
    public @Nullable IBinder onBind(@NonNull Intent intent) {
        if (!SERVICE_INTERFACE.equals(intent.getAction())) {
            return null;
        }
        return mWrapper;
    }

    /**
     * The result of sending an MMS.
     */
    public static final class SendMmsResult {
        private int mSendStatus;
        private byte[] mSendConfPdu;

        /**
         * Constructs a SendMmsResult with the MMS send result, and the SendConf PDU.
         *
         * @param sendStatus send status, one of {@link #SEND_STATUS_OK},
         *        {@link #SEND_STATUS_RETRY_ON_CARRIER_NETWORK}, and
         *        {@link #SEND_STATUS_ERROR}
         * @param sendConfPdu a possibly {code null} SendConf PDU, which confirms that the message
         *        was sent. sendConfPdu is ignored if the {@code result} is not
         *        {@link #SEND_STATUS_OK}.
         */
        public SendMmsResult(int sendStatus, @Nullable byte[] sendConfPdu) {
            mSendStatus = sendStatus;
            mSendConfPdu = sendConfPdu;
        }

        /**
         * Returns the send status of the just-sent MMS.
         *
         * @return the send status which is one of {@link #SEND_STATUS_OK},
         *         {@link #SEND_STATUS_RETRY_ON_CARRIER_NETWORK}, and {@link #SEND_STATUS_ERROR}
         */
        public int getSendStatus() {
            return mSendStatus;
        }

        /**
         * Returns the SendConf PDU, which confirms that the message was sent.
         *
         * @return the SendConf PDU
         */
        public @Nullable byte[] getSendConfPdu() {
            return mSendConfPdu;
        }
    }

    /**
     * The result of sending an SMS.
     */
    public static final class SendSmsResult {
        private final int mSendStatus;
        private final int mMessageRef;

        /**
         * Constructs a SendSmsResult with the send status and message reference for the
         * just-sent SMS.
         *
         * @param sendStatus send status, one of {@link #SEND_STATUS_OK},
         *        {@link #SEND_STATUS_RETRY_ON_CARRIER_NETWORK}, and {@link #SEND_STATUS_ERROR}.
         * @param messageRef message reference of the just-sent SMS. This field is applicable only
         *        if send status is {@link #SEND_STATUS_OK}.
         */
        public SendSmsResult(int sendStatus, int messageRef) {
            mSendStatus = sendStatus;
            mMessageRef = messageRef;
        }

        /**
         * Returns the message reference of the just-sent SMS.
         *
         * @return the message reference
         */
        public int getMessageRef() {
            return mMessageRef;
        }

        /**
         * Returns the send status of the just-sent SMS.
         *
         * @return the send status
         */
        public int getSendStatus() {
            return mSendStatus;
        }
    }

    /**
     * The result of sending a multipart SMS.
     */
    public static final class SendMultipartSmsResult {
        private final int mSendStatus;
        private final int[] mMessageRefs;

        /**
         * Constructs a SendMultipartSmsResult with the send status and message references for the
         * just-sent multipart SMS.
         *
         * @param sendStatus send status, one of {@link #SEND_STATUS_OK},
         *        {@link #SEND_STATUS_RETRY_ON_CARRIER_NETWORK}, and {@link #SEND_STATUS_ERROR}.
         * @param messageRefs an array of message references, one for each part of the
         *        multipart SMS. This field is applicable only if send status is
         *        {@link #SEND_STATUS_OK}.
         */
        public SendMultipartSmsResult(int sendStatus, @Nullable int[] messageRefs) {
            mSendStatus = sendStatus;
            mMessageRefs = messageRefs;
        }

        /**
         * Returns the message references of the just-sent multipart SMS.
         *
         * @return the message references, one for each part of the multipart SMS
         */
        public @Nullable int[] getMessageRefs() {
            return mMessageRefs;
        }

        /**
         * Returns the send status of the just-sent SMS.
         *
         * @return the send status
         */
        public int getSendStatus() {
            return mSendStatus;
        }
    }

    /**
     * A callback interface used to provide results asynchronously.
     */
    public interface ResultCallback<T> {
        /**
         * Invoked when the result is available.
         *
         * @param result the result
         */
        public void onReceiveResult(@NonNull T result) throws RemoteException;
    };

    /**
     * A wrapper around ICarrierMessagingService to enable the carrier messaging app to implement
     * methods it cares about in the {@link ICarrierMessagingService} interface.
     */
    private class ICarrierMessagingWrapper extends ICarrierMessagingService.Stub {
        @Override
        public void filterSms(MessagePdu pdu, String format, int destPort,
                              int subId, final ICarrierMessagingCallback callback) {
            onReceiveTextSms(pdu, format, destPort, subId,
                new ResultCallback<Integer>() {
                    @Override
                    public void onReceiveResult(Integer options) throws RemoteException {
                        callback.onFilterComplete(options);
                    }
                });
        }

        @Override
        public void sendTextSms(String text, int subId, String destAddress,
                int sendSmsFlag, final ICarrierMessagingCallback callback) {
            onSendTextSms(text, subId, destAddress, sendSmsFlag,
                    new ResultCallback<SendSmsResult>() {
                    @Override
                    public void onReceiveResult(final SendSmsResult result) throws RemoteException {
                        callback.onSendSmsComplete(result.getSendStatus(), result.getMessageRef());
                    }
                });
        }

        @Override
        public void sendDataSms(byte[] data, int subId, String destAddress, int destPort,
                int sendSmsFlag, final ICarrierMessagingCallback callback) {
            onSendDataSms(data, subId, destAddress, destPort, sendSmsFlag,
                    new ResultCallback<SendSmsResult>() {
                    @Override
                    public void onReceiveResult(final SendSmsResult result) throws RemoteException {
                        callback.onSendSmsComplete(result.getSendStatus(), result.getMessageRef());
                    }
                });
        }

        @Override
        public void sendMultipartTextSms(List<String> parts, int subId, String destAddress,
                int sendSmsFlag, final ICarrierMessagingCallback callback) {
            onSendMultipartTextSms(parts, subId, destAddress, sendSmsFlag,
                        new ResultCallback<SendMultipartSmsResult>() {
                                @Override
                                public void onReceiveResult(final SendMultipartSmsResult result)
                                        throws RemoteException {
                                    callback.onSendMultipartSmsComplete(
                                            result.getSendStatus(), result.getMessageRefs());
                                }
                            });
        }

        @Override
        public void sendMms(Uri pduUri, int subId, Uri location,
                final ICarrierMessagingCallback callback) {
            onSendMms(pduUri, subId, location, new ResultCallback<SendMmsResult>() {
                    @Override
                    public void onReceiveResult(final SendMmsResult result) throws RemoteException {
                        callback.onSendMmsComplete(result.getSendStatus(), result.getSendConfPdu());
                    }
                });
        }

        @Override
        public void downloadMms(Uri pduUri, int subId, Uri location,
                final ICarrierMessagingCallback callback) {
            onDownloadMms(pduUri, subId, location, new ResultCallback<Integer>() {
                    @Override
                    public void onReceiveResult(Integer result) throws RemoteException {
                        callback.onDownloadMmsComplete(result);
                    }
                });
        }
    }
}