ホーム › Networking.WindowsWebServices › WsSendMessage

WsSendMessage

関数

チャネル経由でメッセージを送信する。

DLLwebservices.dll呼出規約winapi対応OSWindows 7 以降

シグネチャ

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

HRESULT WsSendMessage(
    WS_CHANNEL* channel,
    WS_MESSAGE* message,
    const WS_MESSAGE_DESCRIPTION* messageDescription,
    WS_WRITE_OPTION writeOption,
    const void* bodyValue,   // optional
    DWORD bodyValueSize,
    const WS_ASYNC_CONTEXT* asyncContext,   // optional
    WS_ERROR* error   // optional
);

パラメーター

名前	型	方向	説明
channel	WS_CHANNEL*	in	メッセージの送信に使用するチャネル。
message	WS_MESSAGE*	in	送信に使用するメッセージオブジェクト。メッセージオブジェクトは WS_MESSAGE_STATE_EMPTY または WS_MESSAGE_STATE_INITIALIZED の状態である必要があります。
messageDescription	WS_MESSAGE_DESCRIPTION*	in	WS_MESSAGE_DESCRIPTION の action フィールドが、メッセージの action ヘッダーとして使用されます。action が不要な場合、このフィールドは NULL でもかまいません。 WS_MESSAGE_DESCRIPTION の bodyElementDescription フィールドは、メッセージの本文をシリアル化するために使用されます。本文要素が不要な場合、このフィールドは NULL でもかまいません。bodyElementDescription が値のシリアル化にどのように使用されるかについては、WsWriteBody を参照してください。
writeOption	WS_WRITE_OPTION	in	本文要素が必須かどうか、および値をどのように割り当てるか。これは本文要素が必要な場合にのみ使用されます。詳細については、WS_WRITE_OPTION および WsWriteBody を参照してください。
bodyValue	void*	inoptional	メッセージの本文にシリアル化する値。
bodyValueSize	DWORD	in	シリアル化する値のサイズ (バイト単位)。
asyncContext	WS_ASYNC_CONTEXT*	inoptional	関数を非同期に呼び出す方法に関する情報。同期的に呼び出す場合は NULL。
error	WS_ERROR*	inoptional	関数が失敗した場合に、追加のエラー情報を格納する場所を指定します。

戻り値の型: HRESULT

公式ドキュメント

シリアル化を使用して本文要素を書き込み、チャネル上でメッセージを送信します。

戻り値

この関数は、次のいずれかの値を返すことがあります。

戻り値	説明
WS_S_ASYNC	非同期操作はまだ保留中です。
WS_E_OPERATION_ABORTED	操作は中止されました。
WS_E_INVALID_OPERATION	オブジェクトの現在の状態では、この操作は許可されていません。
WS_E_ENDPOINT_NOT_FOUND	リモートエンドポイントが存在しないか、見つかりませんでした。
WS_E_ENDPOINT_ACCESS_DENIED	リモートエンドポイントによってアクセスが拒否されました。
WS_E_ENDPOINT_DISCONNECTED	リモートエンドポイントとの接続が終了しました。
WS_E_ENDPOINT_FAILURE	リモートエンドポイントは要求を処理できませんでした。
WS_E_ENDPOINT_NOT_AVAILABLE	リモートエンドポイントは、現在この場所でサービスを提供していません。
WS_E_ENDPOINT_TOO_BUSY	リモートエンドポイントは負荷が高すぎるため、要求を処理できません。
WS_E_ENDPOINT_UNREACHABLE	リモートエンドポイントに到達できませんでした。
WS_E_INVALID_ENDPOINT_URL	エンドポイントアドレスの URL が無効です。
WS_E_INVALID_FORMAT	入力データが期待される形式ではないか、期待される値ではありませんでした。
WS_E_OPERATION_TIMED_OUT	操作が割り当てられた時間内に完了しませんでした。
WS_E_PROXY_ACCESS_DENIED	HTTP プロキシサーバーによってアクセスが拒否されました。
WS_E_PROXY_FAILURE	HTTP プロキシサーバーは要求を処理できませんでした。
WS_E_QUOTA_EXCEEDED	クォータを超過しました。
WS_E_SECURITY_VERIFICATION_FAILURE	受信したデータのセキュリティ検証に失敗しました。
WS_E_SECURITY_SYSTEM_FAILURE	Windows Web Services フレームワークでセキュリティ操作が失敗しました。
WS_E_SECURITY_TOKEN_EXPIRED	セキュリティトークンの有効期限が切れているため、サーバーによって拒否されました。
WS_E_PROXY_REQUIRES_BASIC_AUTH	HTTP プロキシサーバーは HTTP 認証方式 'basic' を必要とします。
WS_E_PROXY_REQUIRES_DIGEST_AUTH	HTTP プロキシサーバーは HTTP 認証方式 'digest' を必要とします。
WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH	HTTP プロキシサーバーは HTTP 認証方式 'negotiate' を必要とします。
WS_E_PROXY_REQUIRES_NTLM_AUTH	HTTP プロキシサーバーは HTTP 認証方式 'NTLM' を必要とします。
WS_E_SERVER_REQUIRES_BASIC_AUTH	リモートエンドポイントは HTTP 認証方式 'basic' を必要とします。
WS_E_SERVER_REQUIRES_DIGEST_AUTH	リモートエンドポイントは HTTP 認証方式 'digest' を必要とします。
WS_E_SERVER_REQUIRES_NEGOTIATE_AUTH	リモートエンドポイントは HTTP 認証方式 'negotiate' を必要とします。
WS_E_SERVER_REQUIRES_NTLM_AUTH	リモートエンドポイントは HTTP 認証方式 'NTLM' を必要とします。
CERT_E_EXPIRED	現在のシステムクロック、または署名済みファイル内のタイムスタンプと照合したときに、必要な証明書が有効期間内にありません。
CERT_E_CN_NO_MATCH	証明書の CN 名が、渡された値と一致しません。
CERT_E_UNTRUSTEDROOT	証明書チェーンは処理されましたが、信頼プロバイダーによって信頼されていないルート証明書で終了しました。
CERT_E_WRONG_USAGE	この証明書は、要求された用途には有効ではありません。
CRYPT_E_REVOCATION_OFFLINE	失効サーバーがオフラインであったため、失効関数は失効を確認できませんでした。
E_OUTOFMEMORY	メモリが不足しました。
E_INVALIDARG	1 つ以上の引数が無効です。
その他のエラー	この関数は、上記以外のエラーを返すことがあります。

解説(Remarks)

メッセージにカスタムヘッダーを含めるには、WsInitializeMessage で WS_BLANK_MESSAGE を指定してメッセージを初期化し、この関数を呼び出す前に WsAddCustomHeader を使用してヘッダーを追加します。

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

各言語での呼び出し定義

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

HRESULT WsSendMessage(
    WS_CHANNEL* channel,
    WS_MESSAGE* message,
    const WS_MESSAGE_DESCRIPTION* messageDescription,
    WS_WRITE_OPTION writeOption,
    const void* bodyValue,   // optional
    DWORD bodyValueSize,
    const WS_ASYNC_CONTEXT* asyncContext,   // optional
    WS_ERROR* error   // optional
);

[DllImport("webservices.dll", ExactSpelling = true)]
static extern int WsSendMessage(
    ref IntPtr channel,   // WS_CHANNEL*
    ref IntPtr message,   // WS_MESSAGE*
    IntPtr messageDescription,   // WS_MESSAGE_DESCRIPTION*
    int writeOption,   // WS_WRITE_OPTION
    IntPtr bodyValue,   // void* optional
    uint bodyValueSize,   // DWORD
    IntPtr asyncContext,   // WS_ASYNC_CONTEXT* optional
    IntPtr error   // WS_ERROR* optional
);

<DllImport("webservices.dll", ExactSpelling:=True)>
Public Shared Function WsSendMessage(
    ByRef channel As IntPtr,   ' WS_CHANNEL*
    ByRef message As IntPtr,   ' WS_MESSAGE*
    messageDescription As IntPtr,   ' WS_MESSAGE_DESCRIPTION*
    writeOption As Integer,   ' WS_WRITE_OPTION
    bodyValue As IntPtr,   ' void* optional
    bodyValueSize As UInteger,   ' DWORD
    asyncContext As IntPtr,   ' WS_ASYNC_CONTEXT* optional
    [error] As IntPtr   ' WS_ERROR* optional
) As Integer
End Function

' channel : WS_CHANNEL*
' message : WS_MESSAGE*
' messageDescription : WS_MESSAGE_DESCRIPTION*
' writeOption : WS_WRITE_OPTION
' bodyValue : void* optional
' bodyValueSize : DWORD
' asyncContext : WS_ASYNC_CONTEXT* optional
' error : WS_ERROR* optional
Declare PtrSafe Function WsSendMessage Lib "webservices" ( _
    ByRef channel As LongPtr, _
    ByRef message As LongPtr, _
    ByVal messageDescription As LongPtr, _
    ByVal writeOption As Long, _
    ByVal bodyValue As LongPtr, _
    ByVal bodyValueSize As Long, _
    ByVal asyncContext As LongPtr, _
    ByVal error As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WsSendMessage = ctypes.windll.webservices.WsSendMessage
WsSendMessage.restype = ctypes.c_int
WsSendMessage.argtypes = [
    ctypes.c_void_p,  # channel : WS_CHANNEL*
    ctypes.c_void_p,  # message : WS_MESSAGE*
    ctypes.c_void_p,  # messageDescription : WS_MESSAGE_DESCRIPTION*
    ctypes.c_int,  # writeOption : WS_WRITE_OPTION
    ctypes.POINTER(None),  # bodyValue : void* optional
    wintypes.DWORD,  # bodyValueSize : DWORD
    ctypes.c_void_p,  # asyncContext : WS_ASYNC_CONTEXT* optional
    ctypes.c_void_p,  # error : WS_ERROR* optional
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('webservices.dll')
WsSendMessage = Fiddle::Function.new(
  lib['WsSendMessage'],
  [
    Fiddle::TYPE_VOIDP,  # channel : WS_CHANNEL*
    Fiddle::TYPE_VOIDP,  # message : WS_MESSAGE*
    Fiddle::TYPE_VOIDP,  # messageDescription : WS_MESSAGE_DESCRIPTION*
    Fiddle::TYPE_INT,  # writeOption : WS_WRITE_OPTION
    Fiddle::TYPE_VOIDP,  # bodyValue : void* optional
    -Fiddle::TYPE_INT,  # bodyValueSize : DWORD
    Fiddle::TYPE_VOIDP,  # asyncContext : WS_ASYNC_CONTEXT* optional
    Fiddle::TYPE_VOIDP,  # error : WS_ERROR* optional
  ],
  Fiddle::TYPE_INT)

#[link(name = "webservices")]
extern "system" {
    fn WsSendMessage(
        channel: *mut isize,  // WS_CHANNEL*
        message: *mut isize,  // WS_MESSAGE*
        messageDescription: *const WS_MESSAGE_DESCRIPTION,  // WS_MESSAGE_DESCRIPTION*
        writeOption: i32,  // WS_WRITE_OPTION
        bodyValue: *const (),  // void* optional
        bodyValueSize: u32,  // DWORD
        asyncContext: *const WS_ASYNC_CONTEXT,  // WS_ASYNC_CONTEXT* optional
        error: *mut isize  // WS_ERROR* optional
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("webservices.dll")]
public static extern int WsSendMessage(ref IntPtr channel, ref IntPtr message, IntPtr messageDescription, int writeOption, IntPtr bodyValue, uint bodyValueSize, IntPtr asyncContext, IntPtr error);
"@
$api = Add-Type -MemberDefinition $sig -Name 'webservices_WsSendMessage' -Namespace Win32 -PassThru
# $api::WsSendMessage(channel, message, messageDescription, writeOption, bodyValue, bodyValueSize, asyncContext, error)

#uselib "webservices.dll"
#func global WsSendMessage "WsSendMessage" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; WsSendMessage varptr(channel), varptr(message), varptr(messageDescription), writeOption, bodyValue, bodyValueSize, varptr(asyncContext), varptr(error)   ; 戻り値は stat
; channel : WS_CHANNEL* -> "sptr"
; message : WS_MESSAGE* -> "sptr"
; messageDescription : WS_MESSAGE_DESCRIPTION* -> "sptr"
; writeOption : WS_WRITE_OPTION -> "sptr"
; bodyValue : void* optional -> "sptr"
; bodyValueSize : DWORD -> "sptr"
; asyncContext : WS_ASYNC_CONTEXT* optional -> "sptr"
; error : WS_ERROR* optional -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "webservices.dll"
#cfunc global WsSendMessage "WsSendMessage" var, var, var, int, sptr, int, var, var
; res = WsSendMessage(channel, message, messageDescription, writeOption, bodyValue, bodyValueSize, asyncContext, error)
; channel : WS_CHANNEL* -> "var"
; message : WS_MESSAGE* -> "var"
; messageDescription : WS_MESSAGE_DESCRIPTION* -> "var"
; writeOption : WS_WRITE_OPTION -> "int"
; bodyValue : void* optional -> "sptr"
; bodyValueSize : DWORD -> "int"
; asyncContext : WS_ASYNC_CONTEXT* optional -> "var"
; error : WS_ERROR* optional -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "webservices.dll"
#cfunc global WsSendMessage "WsSendMessage" sptr, sptr, sptr, int, sptr, int, sptr, sptr
; res = WsSendMessage(varptr(channel), varptr(message), varptr(messageDescription), writeOption, bodyValue, bodyValueSize, varptr(asyncContext), varptr(error))
; channel : WS_CHANNEL* -> "sptr"
; message : WS_MESSAGE* -> "sptr"
; messageDescription : WS_MESSAGE_DESCRIPTION* -> "sptr"
; writeOption : WS_WRITE_OPTION -> "int"
; bodyValue : void* optional -> "sptr"
; bodyValueSize : DWORD -> "int"
; asyncContext : WS_ASYNC_CONTEXT* optional -> "sptr"
; error : WS_ERROR* optional -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。