ホーム › NetworkManagement.MobileBroadband › IMbnSms

IMbnSms

COM

📘 Microsoft Learn (日本語) · English

IIDdcbbbab6-2015-4bbb-aaee-338e368af6fa継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

メッセージの送受信、およびメッセージング構成の制御を行うための SMS インターフェイス。

解説(Remarks)

呼び出し元アプリケーションは、IMbnInterface の QueryInterface メソッドを呼び出すことでこのインターフェイスを取得できます。

メソッド 8

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetSmsConfiguration(IMbnSmsConfiguration** smsConfiguration)

デバイスの SMS 構成を取得します。

smsConfiguration

IMbnSmsConfiguration**

out

デバイスの SMS 構成を表す IMbnSmsConfiguration インターフェイス。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_PENDING	SMS 構成は利用できません。モバイルブロードバンドサービスがデバイスに情報を照会しています。呼び出し元アプリケーションは、IMbnSmsEvents インターフェイスの OnSmsConfigurationChange メソッドを登録することで、SMS 構成が利用可能になったときに通知を受け取ることができます。
E_MBN_PIN_REQUIRED	この情報を取得するには PIN が必要です。
E_MBN_SIM_NOT_INSERTED	デバイスに SIM がありません。
E_MBN_BAD_SIM	デバイスに不良な SIM があります。
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	デバイスは SMS をサポートしていません。

解説(Remarks)

E_MBN_PIN_REQUIRED、E_MBN_SIM_NOT_INSERTED、E_MBN_BAD_SIM などの回復可能なエラーの場合、モバイルブロードバンドサービスは、エラー状態が解消されたときにデバイスに対してこの情報を再度照会します。たとえば、この情報を取得するためにデバイスが PIN の入力を必要とする場合、E_MBN_PIN_REQUIRED が返されます。アプリケーションがデバイスのロックを解除するために PIN を入力すると、モバイルブロードバンドサービスはデバイスからこの情報を再度取得しようとします。モバイルブロードバンドサービスは、IMbnSmsEvents インターフェイスの OnSmsConfigurationChange メソッドを呼び出します。

SMS 構成は、いずれのアプリケーションからの変更要求もなしに、ネットワークまたはデバイスによって更新されることがあります。そのような場合、モバイルブロードバンドサービスは、IMbnSmsEvents インターフェイスの OnSmsConfigurationChange メソッドを呼び出して、登録済みのすべてのアプリケーションに通知します。

vtbl 4 HRESULT SetSmsConfiguration(IMbnSmsConfiguration* smsConfiguration, DWORD* requestID)

デバイスの SMS 構成を更新します。

smsConfiguration	IMbnSmsConfiguration*	in	デバイスを更新するための新しい SMS 構成を表す IMbnSmsConfiguration インターフェイス。
requestID	DWORD*	out	この要求を識別するためにモバイルブロードバンドサービスによって発行された要求 ID へのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	メソッドは正常に完了しました。
HRESULT_FROM_WIN32(ERROR_SERVICE_NOT_ACTIVE)	モバイルブロードバンドサービスがシステム上で実行されていません。
E_HANDLE	インターフェイスは無効です。おそらくデバイスがシステムから取り外されたためです。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	インターフェイスは無効です。おそらくモバイルブロードバンドデバイスがシステムから取り外されています。

解説(Remarks)

アプリケーションは SetSmsConfiguration を使用して、デバイス内の既定の SMS サービスセンターアドレスを変更できます。

アプリケーションは、デバイスの SMS 構成を設定するために次の手順を実行する必要があります。

GetSmsConfiguration を呼び出して IMbnSmsConfiguration インターフェイスを取得します。
手順 1 で取得した IMbnSmsConfiguration インターフェイスを、構成に対する目的の変更を反映した新しい値で変更します。
変更した IMbnSmsConfiguration を SetSmsConfiguration に渡します。

これは非同期操作であり、すぐに制御を返します。メソッドがエラーなしで制御を返した場合、モバイルブロードバンドサービスは IMbnSmsEvents インターフェイスの OnSetSmsConfigurationComplete メソッドを呼び出します。

vtbl 5 HRESULT SmsSendPdu(LPWSTR pduData, BYTE size, DWORD* requestID)

PDU 形式でメッセージを送信します。

pduData	LPWSTR	in	16 進数形式の PDU メッセージを表す文字列。
size	BYTE	in	16 進文字列形式に変換する前の、サービスセンターアドレスの長さを除いた PDU メッセージのサイズ (バイト数)。
requestID	DWORD*	out	この要求を識別するためにモバイルブロードバンドサービスによって発行された要求 ID へのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	pduData または size が無効です。
HRESULT_FROM_WIN32(ERROR_SERVICE_NOT_ACTIVE)	モバイルブロードバンドサービスがこのシステム上で実行されていません。
E_HANDLE	インターフェイスは無効です。おそらくデバイスがシステムから取り外されたためです。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	インターフェイスは無効です。おそらくモバイルブロードバンドデバイスがシステムから取り外されています。
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	デバイスは要求された形式での SMS メッセージ送信をサポートしていません。たとえば、この関数が CDMA デバイスに対して呼び出された場合です。

解説(Remarks)

pduData 内のこのデータは、3GPP TS 27.005 および 3GPP TS 23.040 で定義された PDU 構造に準拠しています。

次の表は、メッセージ "Hello" を含む PDU メッセージがどのように構成されるかの例を示しています。

例	07	91198994000010	11000A9189945086180000AA05C8329BFD06
内容	サービスセンターアドレスのサイズ	サービスセンターアドレス	16 進数形式の PDU
サイズ	1 バイト	可変	可変

この関数は、PDU 形式での SMS 送信をサポートする GSM デバイスに対してのみ呼び出す必要があります。デバイスは、MBN_INTERFACE_CAPS に MBN_SMS_CAPS_PDU_SEND を設定することでこの機能を報告します。

これは非同期操作であり、すぐに制御を返します。メソッドがエラーなしで制御を返した場合、モバイルブロードバンドサービスは IMbnSmsEvents インターフェイスの OnSmsSendComplete メソッドを呼び出します。

vtbl 6 HRESULT SmsSendCdma(LPWSTR address, MBN_SMS_CDMA_ENCODING encoding, MBN_SMS_CDMA_LANG language, DWORD sizeInCharacters, SAFEARRAY* message, DWORD* requestID)

CDMA 形式でメッセージを送信します。

address	LPWSTR	in	受信者の電話番号を含む null 終端文字列。文字列の最大サイズは 15 桁です。
encoding	MBN_SMS_CDMA_ENCODING	in	データエンコードを指定する MBN_SMS_CDMA_ENCODING 値。
language	MBN_SMS_CDMA_LANG	in	言語を指定する MBN_SMS_CDMA_LANG 値。
sizeInCharacters	DWORD	in	メッセージ内のエンコードされた文字数。これはメッセージ配列のサイズとは異なる場合があります。
message	SAFEARRAY*	in	エンコードされた CDMA メッセージを含むバイト配列。この配列の最大サイズは IMbnSmsConfiguration の CdmaShortMsgSize プロパティですが、MBN_CDMA_SHORT_MSG_SIZE_MAX (160) を超えることはできません。
requestID	DWORD*	out	この要求を識別するためにモバイルブロードバンドサービスによって発行された要求 ID へのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	メソッドは正常に完了しました。
HRESULT_FROM_WIN32(ERROR_SERVICE_NOT_ACTIVE)	モバイルブロードバンドサービスがこのシステム上で実行されていません。
E_HANDLE	インターフェイスは無効です。おそらくデバイスがシステムから取り外されたためです。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	インターフェイスは無効です。おそらくモバイルブロードバンドデバイスがシステムから取り外されています。
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	デバイスは要求された形式での SMS メッセージ送信をサポートしていません。たとえば、この関数が GSM デバイスに対して呼び出された場合です。

解説(Remarks)

このメソッドは、CDMA デバイスで SMS メッセージを送信するために使用できます。ただし、これは CDMA デバイスが SMS 送信をサポートしている場合に限られます。呼び出し元アプリケーションは、IMbnInterface の GetInterfaceCapability メソッドを呼び出すことで、デバイスがこの形式をサポートしているかどうかを確認できます。その後、MBN_INTERFACE_CAPS の smsCaps メンバーで MBN_SMS_CAPS_TEXT_SEND を確認できます。

address パラメーターは、次のいずれかの形式にできます。

"+ <国際国番号> <SMS サービスセンター番号>\0"
"<SMS サービスセンター番号>\0"

vtbl 7 HRESULT SmsSendCdmaPdu(SAFEARRAY* message, DWORD* requestID)

CDMA バイナリ形式でメッセージを送信します。

message	SAFEARRAY*	in	3GPP2 仕様 C.S0015-A “Short Message Service (SMS) for Wideband Spread Spectrum Systems” の "SMS Point-to-Point Message” のセクション 3.4.2.1 に従ってエンコードされた CDMA メッセージを表すバイト配列。SMS は Wireless Messaging Teleservice (WMT) 形式のみをサポートします。
requestID	DWORD*	out	この要求を識別するためにモバイルブロードバンドサービスによって発行された要求 ID へのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	メソッドは正常に完了しました。
HRESULT_FROM_WIN32(ERROR_SERVICE_NOT_ACTIVE)	モバイルブロードバンドサービスがこのシステム上で実行されていません。
E_HANDLE	インターフェイスは無効です。おそらくデバイスがシステムから取り外されたためです。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	インターフェイスは無効です。おそらくモバイルブロードバンドデバイスがシステムから取り外されています。
E_INVALIDARG	message が無効です。
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	デバイスは要求された形式での SMS メッセージ送信をサポートしていません。たとえば、この関数が GSM デバイスに対して呼び出された場合です。

解説(Remarks)

このメソッドは CDMA デバイスにのみ適用されます。

SmsSendCdmaPdu は、3GPP2 仕様 C.S0015-A “Short Message Service (SMS) for Wideband Spread Spectrum Systems” の "SMS Point-to-Point Message” のセクション 3.4.2.1 に従ってエンコードされたバイナリ形式で SMS メッセージを送信するために使用できます。SMS は Wireless Messaging Teleservice (WMT) 形式のみをサポートします。

SmsSendCdmaPdu は、CDMA デバイスがバイナリ形式での SMS 送信をサポートしている場合にのみ呼び出す必要があります。デバイスは、MBN_INTERFACE_CAPS に MBN_SMS_PDU_SEND を設定することでこの形式を報告します。

これは非同期操作であり、メソッド呼び出しはすぐに制御を返します。メソッドがエラーなしで制御を返した場合、操作は非同期的に実行されます。Windows は、IMbnSmsEvents の OnSmsSendComplete メソッドを呼び出して、操作の完了状態をアプリケーションに通知します。

vtbl 8 HRESULT SmsRead(MBN_SMS_FILTER* smsFilter, MBN_SMS_FORMAT smsFormat, DWORD* requestID)

デバイスから一連の SMS メッセージを読み取ります。

smsFilter

MBN_SMS_FILTER*

読み取るメッセージのセットを定義する MBN_SMS_FILTER 構造体へのポインター。

smsFormat

MBN_SMS_FORMAT

SMS メッセージを読み取る形式を指定する MBN_SMS_FORMAT 値。

GSM デバイスの場合、常に MBN_SMS_FORMAT_PDU である必要があります。

CDMA デバイスの場合、これに MBN_SMS_FORMAT_PDU を指定すると、デバイスはバイナリモードの CDMA メッセージを読み取ります。MBN_SMS_FORMAT_TEXT を指定すると、デバイスはテキストモードの CDMA メッセージを読み取ります。デバイスが指定された形式をサポートしていない場合、エラーコードが返されることがあります。

requestID

DWORD*

out

この要求を識別するためにモバイルブロードバンドサービスによって発行された要求 ID へのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	メソッドは正常に完了しました。
HRESULT_FROM_WIN32(ERROR_SERVICE_NOT_ACTIVE)	モバイルブロードバンドサービスがこのシステム上で実行されていません。
E_HANDLE	インターフェイスは無効です。おそらくデバイスがシステムから取り外されたためです。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	インターフェイスは無効です。おそらくモバイルブロードバンドデバイスがシステムから取り外されています。
E_INVALIDARG	smsFormat または smsFilter が無効です。

解説(Remarks)

smsFilter を使用すると、アプリケーションは、新規メッセージ、下書きメッセージ、またはインデックスを使用した特定のメッセージなどの基本フィルターを指定できます。基本フィルターの組み合わせを統合することで、複雑なフィルターを使用できます。すべてのインターフェイスは、インデックスベースのフィルターと新規メッセージタイプのフィルターをサポートします。その他のフィルターのサポートは、一部のインターフェイスでは任意です。指定されたフィルターがサポートされていない場合、操作完了コールバック関数は E_MBN_STATUS_FILTER_NOT_SUPPORTED の状態を返します。

これは非同期操作であり、すぐに制御を返します。メソッドがエラーなしで制御を返した場合、モバイルブロードバンドサービスは IMbnSmsEvents インターフェイスの OnSmsReadComplete メソッドを呼び出します。

vtbl 9 HRESULT SmsDelete(MBN_SMS_FILTER* smsFilter, DWORD* requestID)

デバイスから一連の SMS メッセージを削除します。

smsFilter	MBN_SMS_FILTER*	in	削除するメッセージのセットを定義する MBN_SMS_FILTER 構造体へのポインター。
requestID	DWORD*	out	この要求を識別するためにモバイルブロードバンドサービスによって発行された要求 ID へのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	メソッドは正常に完了しました。
HRESULT_FROM_WIN32(ERROR_SERVICE_NOT_ACTIVE)	モバイルブロードバンドサービスがこのシステム上で実行されていません。
E_HANDLE	インターフェイスは無効です。おそらくデバイスがシステムから取り外されたためです。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	インターフェイスは無効です。おそらくモバイルブロードバンドデバイスがシステムから取り外されています。

解説(Remarks)

これは非同期操作であり、すぐに制御を返します。メソッドがエラーなしで制御を返した場合、モバイルブロードバンドサービスは IMbnSmsEvents インターフェイスの OnSmsDeleteComplete メソッドを呼び出します。

vtbl 10 HRESULT GetSmsStatus(MBN_SMS_STATUS_INFO* smsStatusInfo)

デバイスの SMS 状態を取得します。

smsStatusInfo

MBN_SMS_STATUS_INFO*

out

デバイスの状態情報を含む MBN_SMS_STATUS_INFO 構造体へのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_PENDING	SMS 状態は利用できません。モバイルブロードバンドサービスがデバイスに情報を照会しています。呼び出し元アプリケーションは、IMbnSmsEvents インターフェイスの OnSmsStatusChange メソッドを登録することで、SMS 状態が利用可能になったときに通知を受け取ることができます。
E_MBN_PIN_REQUIRED	この情報を取得するには PIN が必要です。
E_MBN_SIM_NOT_INSERTED	デバイスに SIM が挿入されていません。
E_MBN_BAD_SIM	デバイスに不良な SIM が挿入されています。

解説(Remarks)

SMS メッセージストアの状態は、システムが新しいメッセージを受信したために変化することがあります。メッセージストアの状態が変化するたびに、モバイルブロードバンドサービスは IMbnSmsEvent インターフェイスの OnSmsStatusChange メソッドを呼び出します。

メッセージの読み取りや削除などのアプリケーションが発行した操作によって、MBN_SMS_STATUS_INFO 構造体の flag がリセットされることがあります。このリセットによって発生する SMS ストアの変化では、通知メソッドは呼び出されません。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IMbnSms "{DCBBBAB6-2015-4BBB-AAEE-338E368AF6FA}"
#usecom global IMbnSms IID_IMbnSms "{}"
#comfunc global IMbnSms_GetSmsConfiguration  3 sptr
#comfunc global IMbnSms_SetSmsConfiguration  4 sptr,var
#comfunc global IMbnSms_SmsSendPdu           5 wstr,int,var
#comfunc global IMbnSms_SmsSendCdma          6 wstr,int,int,int,var,var
#comfunc global IMbnSms_SmsSendCdmaPdu       7 var,var
#comfunc global IMbnSms_SmsRead              8 var,int,var
#comfunc global IMbnSms_SmsDelete            9 var,var
#comfunc global IMbnSms_GetSmsStatus         10 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IMbnSms "{DCBBBAB6-2015-4BBB-AAEE-338E368AF6FA}"
#usecom global IMbnSms IID_IMbnSms "{}"
#comfunc global IMbnSms_GetSmsConfiguration  3 sptr
#comfunc global IMbnSms_SetSmsConfiguration  4 sptr,sptr
#comfunc global IMbnSms_SmsSendPdu           5 wstr,int,sptr
#comfunc global IMbnSms_SmsSendCdma          6 wstr,int,int,int,sptr,sptr
#comfunc global IMbnSms_SmsSendCdmaPdu       7 sptr,sptr
#comfunc global IMbnSms_SmsRead              8 sptr,int,sptr
#comfunc global IMbnSms_SmsDelete            9 sptr,sptr
#comfunc global IMbnSms_GetSmsStatus         10 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。