lineGetMessage

関数

アプリのキューからテレフォニーイベントメッセージを取得する。

DLLTAPI32.dll呼出規約winapi

シグネチャ

// TAPI32.dll
#include <windows.h>

INT lineGetMessage(
    DWORD hLineApp,
    LINEMESSAGE* lpMessage,
    DWORD dwTimeout
);

パラメーター

名前	型	方向	説明
hLineApp	DWORD	in	lineInitializeEx によって返されたハンドル。アプリケーションは、 LINEINITIALIZEEXPARAMS 構造体の dwOptions メンバーに LINEINITIALIZEEXOPTION_USEEVENT オプションを設定しておく必要があります。
lpMessage	LINEMESSAGE*	inout	LINEMESSAGE 構造体へのポインター。この関数が正常に復帰すると、この構造体には、アプリケーションへの配信用にキューに入れられていた次のメッセージが格納されます。
dwTimeout	DWORD	in	タイムアウト間隔 (ミリ秒単位)。この間隔が経過すると、メッセージを返せない場合でも関数は復帰します。dwTimeout が 0 の場合、関数はキューに入れられたメッセージの有無を確認し、直ちに復帰します。dwTimeout が INFINITE の場合、関数のタイムアウト間隔が経過することはありません。

戻り値の型: INT

公式ドキュメント

lineGetMessage 関数は、Event Handle 通知メカニズムを使用しているアプリケーションへの配信用にキューに入れられた、次の TAPI メッセージを返します (詳細については lineInitializeEx を参照してください)。

戻り値

要求が成功した場合は 0 を返し、エラーが発生した場合は負のエラー番号を返します。返される可能性のある値は次のとおりです。

LINEERR_INVALAPPHANDLE、LINEERR_OPERATIONFAILED、LINEERR_INVALPOINTER、LINEERR_NOMEM。

解説(Remarks)

lineGetMessage 関数が 0 以外のタイムアウトを指定して呼び出されている状態で、アプリケーションが別のスレッドで lineShutdown を呼び出した場合、この関数は直ちに LINEERR_INVALAPPHANDLE を返して復帰します。

タイムアウトが経過した場合 (またはタイムアウトが 0 であった場合) に、キューからメッセージを取得できなかったときは、この関数はエラー LINEERR_OPERATIONFAILED を返します。

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

各言語での呼び出し定義

// TAPI32.dll
#include <windows.h>

INT lineGetMessage(
    DWORD hLineApp,
    LINEMESSAGE* lpMessage,
    DWORD dwTimeout
);

[DllImport("TAPI32.dll", ExactSpelling = true)]
static extern int lineGetMessage(
    uint hLineApp,   // DWORD
    IntPtr lpMessage,   // LINEMESSAGE* in/out
    uint dwTimeout   // DWORD
);

<DllImport("TAPI32.dll", ExactSpelling:=True)>
Public Shared Function lineGetMessage(
    hLineApp As UInteger,   ' DWORD
    lpMessage As IntPtr,   ' LINEMESSAGE* in/out
    dwTimeout As UInteger   ' DWORD
) As Integer
End Function

' hLineApp : DWORD
' lpMessage : LINEMESSAGE* in/out
' dwTimeout : DWORD
Declare PtrSafe Function lineGetMessage Lib "tapi32" ( _
    ByVal hLineApp As Long, _
    ByVal lpMessage As LongPtr, _
    ByVal dwTimeout As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

lineGetMessage = ctypes.windll.tapi32.lineGetMessage
lineGetMessage.restype = ctypes.c_int
lineGetMessage.argtypes = [
    wintypes.DWORD,  # hLineApp : DWORD
    ctypes.c_void_p,  # lpMessage : LINEMESSAGE* in/out
    wintypes.DWORD,  # dwTimeout : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('TAPI32.dll')
lineGetMessage = Fiddle::Function.new(
  lib['lineGetMessage'],
  [
    -Fiddle::TYPE_INT,  # hLineApp : DWORD
    Fiddle::TYPE_VOIDP,  # lpMessage : LINEMESSAGE* in/out
    -Fiddle::TYPE_INT,  # dwTimeout : DWORD
  ],
  Fiddle::TYPE_INT)

#[link(name = "tapi32")]
extern "system" {
    fn lineGetMessage(
        hLineApp: u32,  // DWORD
        lpMessage: *mut LINEMESSAGE,  // LINEMESSAGE* in/out
        dwTimeout: u32  // DWORD
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("TAPI32.dll")]
public static extern int lineGetMessage(uint hLineApp, IntPtr lpMessage, uint dwTimeout);
"@
$api = Add-Type -MemberDefinition $sig -Name 'TAPI32_lineGetMessage' -Namespace Win32 -PassThru
# $api::lineGetMessage(hLineApp, lpMessage, dwTimeout)

#uselib "TAPI32.dll"
#func global lineGetMessage "lineGetMessage" sptr, sptr, sptr
; lineGetMessage hLineApp, varptr(lpMessage), dwTimeout   ; 戻り値は stat
; hLineApp : DWORD -> "sptr"
; lpMessage : LINEMESSAGE* in/out -> "sptr"
; dwTimeout : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "TAPI32.dll"
#cfunc global lineGetMessage "lineGetMessage" int, var, int
; res = lineGetMessage(hLineApp, lpMessage, dwTimeout)
; hLineApp : DWORD -> "int"
; lpMessage : LINEMESSAGE* in/out -> "var"
; dwTimeout : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "TAPI32.dll"
#cfunc global lineGetMessage "lineGetMessage" int, sptr, int
; res = lineGetMessage(hLineApp, varptr(lpMessage), dwTimeout)
; hLineApp : DWORD -> "int"
; lpMessage : LINEMESSAGE* in/out -> "sptr"
; dwTimeout : DWORD -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。