Added in API level 22

CarrierMessagingService

abstract class CarrierMessagingService : Service
kotlin.Any
   ↳ android.content.Context
   ↳ android.content.ContextWrapper
   ↳ android.app.Service
   ↳ android.service.carrier.CarrierMessagingService

A service that receives calls from the system when new SMS and MMS are sent or received.

To extend this class, you must declare the service in your manifest file with the android.Manifest.permission#BIND_CARRIER_SERVICES permission and include an intent filter with the SERVICE_INTERFACE action. For example:

<service android:name=".MyMessagingService"
           android:label="@string/service_name"
           android:permission="android.permission.BIND_CARRIER_SERVICES">
      <intent-filter>
          <action android:name="android.service.carrier.CarrierMessagingService" />
      </intent-filter>
  </service>

Summary

Nested classes
abstract

A callback interface used to provide results asynchronously.

The result of sending an MMS.

The result of sending a multipart SMS.

The result of sending an SMS.

Constants
static Int

MMS downloading failed.

static Int

Successfully downloaded an MMS message.

static Int

MMS downloading failed.

static Int

The default bitmask value passed to the callback of onReceiveTextSms with all RECEIVE_OPTIONS_x flags cleared to indicate that the message should be kept and a new message notification should be shown.

static Int

Used to set the flag in the bitmask passed to the callback of onReceiveTextSms to indicate that the inbound SMS should be dropped.

static Int

Used to set the flag in the bitmask passed to the callback of 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.

static Int

Flag to request SMS delivery status report.

static Int

SMS/MMS sending failed.

static Int

Indicates that an SMS or MMS message was successfully sent.

static Int

SMS/MMS sending failed.

static String

The android.content.Intent that must be declared as handled by the service.

Inherited constants
Public constructors

Public methods
open IBinder?
onBind(intent: Intent)

Return the communication channel to the service.

open Unit
onDownloadMms(contentUri: Uri, subId: Int, location: Uri, callback: CarrierMessagingService.ResultCallback<Int!>)

Override this method to download MMSs received.

open Unit
onFilterSms(pdu: MessagePdu, format: String, destPort: Int, subId: Int, callback: CarrierMessagingService.ResultCallback<Boolean!>)

Override this method to filter inbound SMS messages.

open Unit
onReceiveTextSms(pdu: MessagePdu, format: String, destPort: Int, subId: Int, callback: CarrierMessagingService.ResultCallback<Int!>)

Override this method to filter inbound SMS messages.

open Unit

Override this method to intercept binary SMSs sent from the device.

open Unit
onSendDataSms(data: ByteArray, subId: Int, destAddress: String, destPort: Int, sendSmsFlag: Int, callback: CarrierMessagingService.ResultCallback<CarrierMessagingService.SendSmsResult!>)

Override this method to intercept binary SMSs sent from the device.

open Unit

Override this method to intercept MMSs sent from the device.

open Unit

Override this method to intercept long SMSs sent from the device.

open Unit

Override this method to intercept long SMSs sent from the device.

open Unit

Override this method to intercept text SMSs sent from the device.

open Unit

Override this method to intercept text SMSs sent from the device.

Inherited functions

Constants

DOWNLOAD_STATUS_ERROR

Added in API level 22
static val DOWNLOAD_STATUS_ERROR: Int

MMS downloading failed. We should not retry via the carrier network.

Value: 2

DOWNLOAD_STATUS_OK

Added in API level 22
static val DOWNLOAD_STATUS_OK: Int

Successfully downloaded an MMS message.

Value: 0

DOWNLOAD_STATUS_RETRY_ON_CARRIER_NETWORK

Added in API level 22
static val DOWNLOAD_STATUS_RETRY_ON_CARRIER_NETWORK: Int

MMS downloading failed. We should retry via the carrier network.

Value: 1

RECEIVE_OPTIONS_DEFAULT

Added in API level 24
static val RECEIVE_OPTIONS_DEFAULT: Int

The default bitmask value passed to the callback of onReceiveTextSms with all RECEIVE_OPTIONS_x flags cleared to indicate that the message should be kept and a new message notification should be shown.

Value: 0

RECEIVE_OPTIONS_DROP

Added in API level 24
static val RECEIVE_OPTIONS_DROP: Int

Used to set the flag in the bitmask passed to the callback of onReceiveTextSms to indicate that the inbound SMS should be dropped.

Value: 1

RECEIVE_OPTIONS_SKIP_NOTIFY_WHEN_CREDENTIAL_PROTECTED_STORAGE_UNAVAILABLE

Added in API level 24
static val RECEIVE_OPTIONS_SKIP_NOTIFY_WHEN_CREDENTIAL_PROTECTED_STORAGE_UNAVAILABLE: Int

Used to set the flag in the bitmask passed to the callback of 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.

Value: 2

SEND_FLAG_REQUEST_DELIVERY_STATUS

Added in API level 23
static val SEND_FLAG_REQUEST_DELIVERY_STATUS: Int

Flag to request SMS delivery status report.

Value: 1

SEND_STATUS_ERROR

Added in API level 22
static val SEND_STATUS_ERROR: Int

SMS/MMS sending failed. We should not retry via the carrier network.

Value: 2

SEND_STATUS_OK

Added in API level 22
static val SEND_STATUS_OK: Int

Indicates that an SMS or MMS message was successfully sent.

Value: 0

SEND_STATUS_RETRY_ON_CARRIER_NETWORK

Added in API level 22
static val SEND_STATUS_RETRY_ON_CARRIER_NETWORK: Int

SMS/MMS sending failed. We should retry via the carrier network.

Value: 1

SERVICE_INTERFACE

Added in API level 22
static val SERVICE_INTERFACE: String

The android.content.Intent that must be declared as handled by the service.

Value: "android.service.carrier.CarrierMessagingService"

Public constructors

CarrierMessagingService

CarrierMessagingService()

Public methods

onBind

Added in API level 22
open fun onBind(intent: Intent): IBinder?

Return the communication channel to the service. May return null if clients can not bind to the service. The returned android.os.IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
intent Intent: This value cannot be null.
Return
IBinder? This value may be null.

onDownloadMms

Added in API level 22
open fun onDownloadMms(
    contentUri: Uri,
    subId: Int,
    location: Uri,
    callback: CarrierMessagingService.ResultCallback<Int!>
): Unit

Override this method to download MMSs received.

Parameters
contentUri Uri: the content provider URI of the PDU to be downloaded. This value cannot be null.
subId Int: SMS subscription ID of the SIM
location Uri: the URI of the message to be downloaded. This value cannot be null.
callback CarrierMessagingService.ResultCallback<Int!>: result callback. Call with a status code which is one of DOWNLOAD_STATUS_OK, DOWNLOAD_STATUS_RETRY_ON_CARRIER_NETWORK, or DOWNLOAD_STATUS_ERROR. This value cannot be null.

onFilterSms

Added in API level 22
Deprecated in API level 24
open fun onFilterSms(
    pdu: MessagePdu,
    format: String,
    destPort: Int,
    subId: Int,
    callback: CarrierMessagingService.ResultCallback<Boolean!>
): Unit

Deprecated: Use onReceiveTextSms instead.

Override this method to filter inbound SMS messages.

Parameters
pdu MessagePdu: the PDUs of the message This value cannot be null.
format String: the format of the PDUs, typically "3gpp" or "3gpp2" This value cannot be null.
destPort Int: the destination port of a binary SMS, this will be -1 for text SMS
subId Int: SMS subscription ID of the SIM
callback CarrierMessagingService.ResultCallback<Boolean!>: result callback. Call with true to keep an inbound SMS message and deliver to SMS apps, and false to drop the message. This value cannot be null.

onReceiveTextSms

Added in API level 24
open fun onReceiveTextSms(
    pdu: MessagePdu,
    format: String,
    destPort: Int,
    subId: Int,
    callback: CarrierMessagingService.ResultCallback<Int!>
): Unit

Override this method to filter inbound SMS messages.

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 RECEIVE_OPTIONS_DROP is not set when invoking the callback.

Parameters
pdu MessagePdu: the PDUs of the message This value cannot be null.
format String: the format of the PDUs, typically "3gpp" or "3gpp2" This value cannot be null.
destPort Int: the destination port of a binary SMS, this will be -1 for text SMS
subId Int: SMS subscription ID of the SIM
callback CarrierMessagingService.ResultCallback<Int!>: result callback. Call with a bitmask integer to indicate how the incoming text SMS should be handled by the platform. Use RECEIVE_OPTIONS_DROP and RECEIVE_OPTIONS_SKIP_NOTIFY_WHEN_CREDENTIAL_PROTECTED_STORAGE_UNAVAILABLE to set the flags in the bitmask. This value cannot be null.

onSendDataSms

Added in API level 22
Deprecated in API level 23
open fun onSendDataSms(
    data: ByteArray,
    subId: Int,
    destAddress: String,
    destPort: Int,
    callback: CarrierMessagingService.ResultCallback<CarrierMessagingService.SendSmsResult!>
): Unit

Deprecated: Override #onSendDataSms below instead.

Override this method to intercept binary SMSs sent from the device.

Parameters
data ByteArray: the binary content This value cannot be null.
subId Int: SMS subscription ID of the SIM
destAddress String: phone number of the recipient of the message This value cannot be null.
destPort Int: the destination port
callback CarrierMessagingService.ResultCallback<CarrierMessagingService.SendSmsResult!>: result callback. Call with a SendSmsResult. This value cannot be null.

onSendDataSms

Added in API level 23
open fun onSendDataSms(
    data: ByteArray,
    subId: Int,
    destAddress: String,
    destPort: Int,
    sendSmsFlag: Int,
    callback: CarrierMessagingService.ResultCallback<CarrierMessagingService.SendSmsResult!>
): Unit

Override this method to intercept binary SMSs sent from the device.

Parameters
data ByteArray: the binary content This value cannot be null.
subId Int: SMS subscription ID of the SIM
destAddress String: phone number of the recipient of the message This value cannot be null.
destPort Int: the destination port
sendSmsFlag Int: Flag for sending SMS. Acceptable values are 0 and SEND_FLAG_REQUEST_DELIVERY_STATUS.
callback CarrierMessagingService.ResultCallback<CarrierMessagingService.SendSmsResult!>: result callback. Call with a SendSmsResult. This value cannot be null.

onSendMms

Added in API level 22
open fun onSendMms(
    pduUri: Uri,
    subId: Int,
    location: Uri?,
    callback: CarrierMessagingService.ResultCallback<CarrierMessagingService.SendMmsResult!>
): Unit

Override this method to intercept MMSs sent from the device.

Parameters
pduUri Uri: the content provider URI of the PDU to send This value cannot be null.
subId Int: SMS subscription ID of the SIM
location Uri?: the optional URI to send this MMS PDU. If this is {code null}, the PDU should be sent to the default MMSC URL.
callback CarrierMessagingService.ResultCallback<CarrierMessagingService.SendMmsResult!>: result callback. Call with a SendMmsResult. This value cannot be null.

onSendMultipartTextSms

Added in API level 22
Deprecated in API level 23
open fun onSendMultipartTextSms(
    parts: MutableList<String!>,
    subId: Int,
    destAddress: String,
    callback: CarrierMessagingService.ResultCallback<CarrierMessagingService.SendMultipartSmsResult!>
): Unit

Deprecated: Override #onSendMultipartTextSms below instead.

Override this method to intercept long SMSs sent from the device.

Parameters
parts MutableList<String!>: a List of the message parts This value cannot be null.
subId Int: SMS subscription ID of the SIM
destAddress String: phone number of the recipient of the message This value cannot be null.
callback CarrierMessagingService.ResultCallback<CarrierMessagingService.SendMultipartSmsResult!>: result callback. Call with a SendMultipartSmsResult. This value cannot be null.

onSendMultipartTextSms

Added in API level 23
open fun onSendMultipartTextSms(
    parts: MutableList<String!>,
    subId: Int,
    destAddress: String,
    sendSmsFlag: Int,
    callback: CarrierMessagingService.ResultCallback<CarrierMessagingService.SendMultipartSmsResult!>
): Unit

Override this method to intercept long SMSs sent from the device.

Parameters
parts MutableList<String!>: a List of the message parts This value cannot be null.
subId Int: SMS subscription ID of the SIM
destAddress String: phone number of the recipient of the message This value cannot be null.
sendSmsFlag Int: Flag for sending SMS. Acceptable values are 0 and SEND_FLAG_REQUEST_DELIVERY_STATUS.
callback CarrierMessagingService.ResultCallback<CarrierMessagingService.SendMultipartSmsResult!>: result callback. Call with a SendMultipartSmsResult. This value cannot be null.

onSendTextSms

Added in API level 22
Deprecated in API level 23
open fun onSendTextSms(
    text: String,
    subId: Int,
    destAddress: String,
    callback: CarrierMessagingService.ResultCallback<CarrierMessagingService.SendSmsResult!>
): Unit

Deprecated: Override #onSendTextSms below instead.

Override this method to intercept text SMSs sent from the device.

Parameters
text String: the text to send This value cannot be null.
subId Int: SMS subscription ID of the SIM
destAddress String: phone number of the recipient of the message This value cannot be null.
callback CarrierMessagingService.ResultCallback<CarrierMessagingService.SendSmsResult!>: result callback. Call with a SendSmsResult. This value cannot be null.

onSendTextSms

Added in API level 23
open fun onSendTextSms(
    text: String,
    subId: Int,
    destAddress: String,
    sendSmsFlag: Int,
    callback: CarrierMessagingService.ResultCallback<CarrierMessagingService.SendSmsResult!>
): Unit

Override this method to intercept text SMSs sent from the device.

Parameters
text String: the text to send This value cannot be null.
subId Int: SMS subscription ID of the SIM
destAddress String: phone number of the recipient of the message This value cannot be null.
sendSmsFlag Int: Flag for sending SMS. Acceptable values are 0 and SEND_FLAG_REQUEST_DELIVERY_STATUS.
callback CarrierMessagingService.ResultCallback<CarrierMessagingService.SendSmsResult!>: result callback. Call with a SendSmsResult. This value cannot be null.