SmsDevice SmsDevice SmsDevice SmsDevice Class

Supports the operation of a mobile broadband SMS device.

Note

This functionality is only available to mobile operator apps and Windows Store app given privileged access by mobile network operators, mobile broadband adapter IHV, or OEM. For more information, see Mobile Broadband: device apps.

Note

Note that this class and its methods are supported for the maintenance of legacy desktop apps that used it in earlier versions of Windows; and if you do use this class, you must specify the Windows.Devices.Sms.LegacySmsApiContract in your app's manifest. Do not use this class if you are developing new apps for Windows 10. Instead, use the members of this namespace that do not require the Windows.Devices.Sms.LegacySmsApiContract.

Syntax

Declaration

public sealed class SmsDevicepublic sealed class SmsDevicePublic NotInheritable Class SmsDevicepublic sealed class SmsDevice

Remarks

Apps that use the ISmsDevice API to send or receive text messages fail with E_ACCESS_DENIED if the user revokes access.

If access to the SMS device has been given to an app:

  • Calling GetDefaultAsync() or FromIdAsync(String) triggers a consent prompt the first time the app is run.
  • The error handlers for the asynchronous methods of GetDefaultAsync() and FromIdAsync(String) receive E_ACCESS_DENIED if the user did not grant permission in the consent prompt or if permission is revoked.
  • If the user re-enables access to SMS after revoking it, call GetDefaultAsync() or FromIdAsync(String) again to access SMS. For example, the error handler for E_ACCESS_DENIED error could display UI to instruct the user to re-enable SMS using the settings charm and to then tap a button to retry accessing SMS. The code behind the button should call GetDefaultAsync() or FromIdAsync(String) before making any other calls.
  • If the app is registering for the SMS background event (SystemTriggerType ), the app has to first call GetDefaultAsync() or FromIdAsync(String) again to access SMS to ensure the app has access. Calling GetDefaultAsync() or FromIdAsync(String) from the background task will not trigger a consent prompt. If it is a first time run or if the user did not grant permission or if permission is revoked then it will receive an E_ACCESS_DENIED.

The first use of the ISmsDevice object to call FromIdAsync(String) or GetDefaultAsync() by applications written in C# or C++ should be on the single-threaded apartment (STA) thread. Calls from a multi-threaded apartment (MTA) thread may result in undefined behavior.

Properties summary

Returns the phone number associated with the SMS device. The phone number can be used to associate incoming messages with the account and possibly an external storage mechanism such as an account inbox.

Returns the cellular class of the SMS device. The class can be used to determine which encodings are appropriate or which device limitations are in effect.

Returns the SMS device's status, which indicates whether the device is ready, or not. It also indicates what type of problem exists if the device is not ready.

Accesses the on-device message store. The store holds messages until a client can retrieve them. On some devices, for example, the store may correspond to the SIM storage for SMS messages.

Methods summary

Estimates the transmitted message length of the specified text message. The estimate can be useful to clients who want to give an indication of how many messages will be sent on the network to carry the text of the full message.

Creates an instance of ISmsDevice for the device that received the SMS message.

Creates an instance of ISmsDevice for the specified Mobile Broadband network account ID.

Creates an instance of an ISmsDevice object associated with the default SMS device. Because the device might be busy, the operation executes asynchronously. The asynchronous operation object returns immediately.

Retrieves the class selection string that can be used to enumerate SMS devices.

Asynchronously sends a message using the SMS device. The method is asynchronous because the send operation might not occur instantaneously. The message operation object is returned immediately.

Events summary

Sets an event handler to be called when the status of the SMS device changes.

Sets an event handler to be called when the device receives a new text message.

Properties

  • AccountPhoneNumber
    AccountPhoneNumber
    AccountPhoneNumber
    AccountPhoneNumber

    Returns the phone number associated with the SMS device. The phone number can be used to associate incoming messages with the account and possibly an external storage mechanism such as an account inbox.

    public string AccountPhoneNumber { get; }public string AccountPhoneNumber { get; }Public ReadOnly Property AccountPhoneNumber As stringpublic string AccountPhoneNumber { get; }

    Property Value

    • string
      string
      string
      string

      A string representation of the account phone number.

  • CellularClass
    CellularClass
    CellularClass
    CellularClass

    Returns the cellular class of the SMS device. The class can be used to determine which encodings are appropriate or which device limitations are in effect.

    public CellularClass CellularClass { get; }public CellularClass CellularClass { get; }Public ReadOnly Property CellularClass As CellularClasspublic CellularClass CellularClass { get; }

    Property Value

  • DeviceStatus
    DeviceStatus
    DeviceStatus
    DeviceStatus

    Returns the SMS device's status, which indicates whether the device is ready, or not. It also indicates what type of problem exists if the device is not ready.

    public SmsDeviceStatus DeviceStatus { get; }public SmsDeviceStatus DeviceStatus { get; }Public ReadOnly Property DeviceStatus As SmsDeviceStatuspublic SmsDeviceStatus DeviceStatus { get; }

    Property Value

  • MessageStore
    MessageStore
    MessageStore
    MessageStore

    Accesses the on-device message store. The store holds messages until a client can retrieve them. On some devices, for example, the store may correspond to the SIM storage for SMS messages.

    public SmsDeviceMessageStore MessageStore { get; }public SmsDeviceMessageStore MessageStore { get; }Public ReadOnly Property MessageStore As SmsDeviceMessageStorepublic SmsDeviceMessageStore MessageStore { get; }

    Property Value

Methods

  • CalculateLength(SmsTextMessage)
    CalculateLength(SmsTextMessage)
    CalculateLength(SmsTextMessage)
    CalculateLength(SmsTextMessage)

    Estimates the transmitted message length of the specified text message. The estimate can be useful to clients who want to give an indication of how many messages will be sent on the network to carry the text of the full message.

    public SmsEncodedLength CalculateLength(SmsTextMessage message)public SmsEncodedLength CalculateLength(SmsTextMessage message)Public Function CalculateLength(message As SmsTextMessage) As SmsEncodedLengthpublic SmsEncodedLength CalculateLength(SmsTextMessage message)

    Parameters

    Returns

  • FromIdAsync(String)
    FromIdAsync(String)
    FromIdAsync(String)
    FromIdAsync(String)

    Creates an instance of ISmsDevice for the device that received the SMS message.

    public static IAsyncOperation<SmsDevice> FromIdAsync(String deviceId)public static IAsyncOperation<SmsDevice> FromIdAsync(String deviceId)Public Static Function FromIdAsync(deviceId As String) As IAsyncOperation( Of SmsDevice )public static IAsyncOperation<SmsDevice> FromIdAsync(String deviceId)

    Parameters

    • deviceId
      System.String
      System.String
      System.String
      System.String

      A string representation of the DeviceInformation ID of the SMS device that received the SMS message.

    Returns

    • The SMS device operation object.

    Remarks

    The SmsReceivedEventDetails interface handles the details of a received message; you can pass the DeviceId ID from that interface to this method to activate the device and retrieve additional message details, such as the sender and the body of the message. Because the device might be busy, the operation executes asynchronously. The asynchronous operation object returns immediately.

  • FromNetworkAccountIdAsync(String)
    FromNetworkAccountIdAsync(String)
    FromNetworkAccountIdAsync(String)
    FromNetworkAccountIdAsync(String)

    Creates an instance of ISmsDevice for the specified Mobile Broadband network account ID.

    public static IAsyncOperation<SmsDevice> FromNetworkAccountIdAsync(String networkAccountId)public static IAsyncOperation<SmsDevice> FromNetworkAccountIdAsync(String networkAccountId)Public Static Function FromNetworkAccountIdAsync(networkAccountId As String) As IAsyncOperation( Of SmsDevice )public static IAsyncOperation<SmsDevice> FromNetworkAccountIdAsync(String networkAccountId)

    Parameters

    • networkAccountId
      System.String
      System.String
      System.String
      System.String

      The Mobile Broadband network account ID to use to select the corresponding mobile broadband device to use for the SMS device

    Returns

    • When this method completes, it returns the SmsDevice for the specified Mobile Broadband network account ID.

  • GetDefaultAsync()
    GetDefaultAsync()
    GetDefaultAsync()
    GetDefaultAsync()

    Creates an instance of an ISmsDevice object associated with the default SMS device. Because the device might be busy, the operation executes asynchronously. The asynchronous operation object returns immediately.

    public static IAsyncOperation<SmsDevice> GetDefaultAsync()public static IAsyncOperation<SmsDevice> GetDefaultAsync()Public Static Function GetDefaultAsync() As IAsyncOperation( Of SmsDevice )public static IAsyncOperation<SmsDevice> GetDefaultAsync()

    Returns

  • GetDeviceSelector()
    GetDeviceSelector()
    GetDeviceSelector()
    GetDeviceSelector()

    Retrieves the class selection string that can be used to enumerate SMS devices.

    public static string GetDeviceSelector()public static string GetDeviceSelector()Public Static Function GetDeviceSelector() As stringpublic static string GetDeviceSelector()

    Returns

    • string
      string
      string
      string

      A reference to an Advanced Query Syntax (AQS) string that identifies an SMS device.

  • SendMessageAsync(ISmsMessage)
    SendMessageAsync(ISmsMessage)
    SendMessageAsync(ISmsMessage)
    SendMessageAsync(ISmsMessage)

    Asynchronously sends a message using the SMS device. The method is asynchronous because the send operation might not occur instantaneously. The message operation object is returned immediately.

    public SendSmsMessageOperation SendMessageAsync(ISmsMessage message)public SendSmsMessageOperation SendMessageAsync(ISmsMessage message)Public Function SendMessageAsync(message As ISmsMessage) As SendSmsMessageOperationpublic SendSmsMessageOperation SendMessageAsync(ISmsMessage message)

    Parameters

    Returns

Events

  • SmsDeviceStatusChanged
    SmsDeviceStatusChanged
    SmsDeviceStatusChanged
    SmsDeviceStatusChanged

    Sets an event handler to be called when the status of the SMS device changes.

    public event SmsDeviceStatusChangedEventHandler SmsDeviceStatusChangedpublic event SmsDeviceStatusChangedEventHandler SmsDeviceStatusChangedPublic Event SmsDeviceStatusChangedpublic event SmsDeviceStatusChangedEventHandler SmsDeviceStatusChanged
  • SmsMessageReceived
    SmsMessageReceived
    SmsMessageReceived
    SmsMessageReceived

    Sets an event handler to be called when the device receives a new text message.

    public event SmsMessageReceivedEventHandler SmsMessageReceivedpublic event SmsMessageReceivedEventHandler SmsMessageReceivedPublic Event SmsMessageReceivedpublic event SmsMessageReceivedEventHandler SmsMessageReceived

Device family

Windows Desktop Extension SDK (introduced v10.0.10240.0)

API contract

Windows.Devices.Sms.LegacySmsApiContract (introduced v1)

Capabilities

cellularMessaging
sms

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.DeprecatedAttribute
Windows.Foundation.Metadata.DualApiPartitionAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute

Details

Assembly

Windows.Devices.Sms.dll