W3Cでは、「SOAPは、非集中型の分散環境で情報を交換するための軽量プロトコルです。XMLベースのプロトコルで、3つの部分から構成されています。メッセージ中にあるものとその処理方法を記述するためのフレームワークを定義するエンベロープ、アプリケーションで定義されるデータ型のインスタンスを表現するための一連のエンコーディング・ルール、リモート・プロシージャ・コールとレスポンスを表現するための規則です。」
SOAPメッセージの構造は次のとおりです。
[SOAP message (XML document) [SOAP envelope [SOAP header? element* ] [SOAP body (element* | Fault)? ] ] ]
この章には、次の項が含まれます。
関連項目:
|
表6-1にSOAP
パッケージのデータ型の概要を示します。
SOAPに関連する例外コードを定義します。
typedef enum SoapExceptionCode { SOAP_UNDEFINED_ERR = 0, SOAP_OTHER_ERR = 1} SoapExceptionCode;
SOAP接続のためのバインディングを定義します。現在選択できるのはHTTPのみです。
typedef enum SoapBinding { BIND_NONE = 0, /* none */ BIND_HTTP = 1 /* HTTP */ } SoapBinding;
SOAPノードのロールを定義します。
typedef enum SoapRole { ROLE_UNSET = 0, /* not specified */ ROLE_NONE = 1, /* "none" */ ROLE_NEXT = 2, /* "next" */ ROLE_ULT = 3 /* "ultimateReceiver" */ } SoapRole;
表6-2にSoapExceptionインタフェースで使用できるメソッドの概要を示します。
表6-2 SoapExceptionインタフェースの概要
データ型 | 説明 |
---|---|
例外に埋め込まれたOracle XMLエラー・コードを取得します。 |
|
Oracle XMLエラー・メッセージを取得します。 |
|
エラー・メッセージの現在の言語エンコーディングを取得します。 |
|
例外に埋め込まれたSOAP例外コードを取得します。 |
例外に埋め込まれたOracle XMLエラー・コードを取得します。これはXMLException
から継承された仮想メンバー関数です。
構文
virtual unsigned getCode() const = 0;
戻り値
(unsigned) 数値のエラー・コード(正常に終了した場合は0)。
Oracle XMLエラー・メッセージを取得します。XMLException
から継承された仮想メンバー関数です。
構文
virtual oratext* getMessage() const = 0;
戻り値
(oratext *) エラー・メッセージ
エラー・メッセージの現在の言語エンコーディングを取得します。XMLException
から継承された仮想メンバー関数です。
構文
virtual oratext* getMesLang() const = 0;
戻り値
(oratext*) エラー・メッセージの現在の言語(エンコーディング)。
例外に埋め込まれたSOAP例外コードを取得します。これは、SOAP API例外コードを戻す、実装で定義済のメンバー関数のプロトタイプを定義する仮想メンバー関数です。
構文
virtual SoapExceptionCode getSoapCode() const = 0;
戻り値
(SoapExceptionCode) 例外コード
表6-3に、使用できるConnectRefインタフェースのメソッドの概要を示します。
デストラクタです。SOAP接続オブジェクトを破棄し、関連付けられていたリソースをすべて解放します。
構文
~ConnectRef() throw (SoapException);
SOAPメッセージを送信し、レスポンスを待機します。
構文
DocumentRef< Node>* call( DocumentRef< Node>& msg) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
送信するSOAPメッセージ |
戻り値
(DocumentRef) 戻されるメッセージ
表6-4にMsgFactoryインタフェースで使用できるメソッドの概要を示します。
表6-4 MsgFactoryインタフェースの概要
データ型 | 説明 |
---|---|
SOAPメッセージ・ファクトリ・インスタンスを破棄します。 |
|
SOAPメッセージ・ファクトリ・インスタンスを作成して戻します。 |
|
SOAPメッセージの本文に要素を追加します。 |
|
他のフォルト原因を追加します。 |
|
SOAPヘッダーに要素を追加します。 |
|
SOAP接続を作成します。 |
|
空のSOAPメッセージを作成して戻します。 |
|
SOAPメッセージを破棄します。 |
|
SOAPメッセージのエンベロープ本文を戻します。 |
|
SOAP本文から要素を取得します。 |
|
SOAPパートのエンベロープを戻します。 |
|
フォルトのコード、理由および詳細を戻します。 |
|
SOAPメッセージのエンベロープ・ヘッダーを戻します。 |
|
SOAPヘッダーから要素を取得します。 |
|
SOAPヘッダー要素から |
|
|
|
特定のインデックスを持つ理由の言語を取得します。 |
|
SOAPヘッダー要素からロールを取得します。 |
|
SOAPメッセージにフォルト・オブジェクトが含まれているかどうかを判別します。 |
|
SOAPメッセージにフォルトを設定します。 |
|
SOAPヘッダー要素に |
|
SOAPヘッダー要素にロールを設定します。 |
デストラクタです。SOAPメッセージ・ファクトリを破棄します。割り当てられたメモリーはすべて解放され、接続はすべて閉じられます。
構文
~MsgFactory() throw (SoapException);
SOAPメッセージ・ファクトリ・インスタンスを作成して戻します。
構文
MsgFactory( Context* ctx_ptr) throw (SoapException);
パラメータ | 説明 |
---|---|
ctx_ptr |
TContext オブジェクト |
戻り値
(MsgFactory) オブジェクト
SOAPメッセージの本文に要素を追加します。
構文
Node* addBodyElement( DocumentRef< Node>& msg, oratext *qname, oratext *uri) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
qname |
追加する要素のQName |
uri |
追加する要素の名前空間URI |
戻り値
(Node*) 作成された要素へのポインタ。
他のフォルト原因を追加します。同じ理由のテキストを別の言語で提供できます。フォルトが作成されると、そのときにプライマリ言語と理由が追加されます。この関数は、その理由の翻訳を追加するのに使用します。
構文
void addFaultReason( DocumentRef< Node>& msg, oratext *reason, oratext *lang) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
reason |
可読的なフォルト理由 |
lang |
理由の言語 |
SOAPヘッダーに要素を追加します。
構文
Node* addHeaderElement( DocumentRef< Node>& msg, oratext *qname, oratext *uri) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
qname |
追加する要素のQName |
uri |
追加する要素の名前空間URI |
戻り値
(Node*) 作成された要素へのポインタ。
SOAP接続オブジェクトを作成します。接続参照オブジェクトはユーザーが明示的に削除する必要があります。
構文
ConnectRef< Node>* createConnection( SoapBinding bind, void *endp, oratext *buf, ubig_ora bufsiz, oratext *msgbuf, ubig_ora msgbufsiz) throw (SoapException);
パラメータ | 説明 |
---|---|
bind |
接続バインディング |
endp |
接続エンド・ポイント |
buf |
データ・バッファ(バッファの割当てを受けるときはNULL ) |
bufsiz |
データ・バッファのサイズ(デフォルトのサイズは0) |
msgbuf |
メッセージ・バッファ(バッファの割当てを受けるときはNULL ) |
msgfubsiz |
メッセージ・バッファのサイズ(デフォルトのサイズは0) |
戻り値
(ConnectRef) 接続オブジェクト
空のSOAPメッセージを作成して戻します。不要になった場合、参照オブジェクトはユーザーが明示的に削除する必要があります。
構文
DocumentRef< Node>* CreateMessage() throw (SoapException);
戻り値
(DocumentRef*) SOAPメッセージ、または例外。
SOAPメッセージを破棄します。
構文
void destroyMessage( DocumentRef< Node>& msg) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ。 |
SOAPメッセージのエンベロープ本文を、本文の要素ノードへのポインタとして戻します。
構文
Node* getBody( DocumentRef<Node>& msg) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
戻り値
(Node*) SOAPメッセージのエンベロープ本文へのポインタ。
SOAP本文から要素を、要素ノードへのポインタとして取得します。
構文
Node* getBodyElement( DocumentRef< Node>& msg, oratext *uri, oratext *local) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
uri |
追加する要素の名前空間URI |
local |
取得する要素のローカル名 |
戻り値
(Node*) 指定した要素へのポインタ。
SOAPパートのエンベロープを、エンベロープ要素ノードへのポインタとして戻します。
構文
Node* getEnvelope( DocumentRef<Node>& msg) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
戻り値
(Node*) SOAPメッセージのエンベロープへのポインタ。
フォルトのコード、理由および詳細を、ユーザー変数を介して戻します。不要なパートにはNULL
を指定できます。lang
については、ポイント先の変数がNULL
である場合、最初の理由に指定するデフォルト言語に設定されます。
構文
Node* getFault( DocumentRef< Node>& msg, oratext **code, oratext **reason, oratext **lang, oratext **node, oratext **role) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
code |
フォルト・コード |
reason |
可読的なフォルト理由 |
lang |
理由に指定する言語またはNULL (デフォルトの言語。最初の理由と同じ) |
node |
フォルト・ノード。 |
role |
ロール: 次、なしまたは最終受信者(バージョン1.1では使用されていません) |
戻り値
(Node) 詳細へのポインタ。
SOAPメッセージのエンベロープ・ヘッダーを、ヘッダーの要素ノードへのポインタとして戻します。
構文
Node* getHeader( DocumentRef< Node>& msg) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
戻り値
(Node*) SOAPメッセージのエンベロープ・ヘッダーへのポインタ。
SOAPヘッダーから要素を、要素ノードへのポインタとして取得します。
構文
Node* getHeaderElement( DocumentRef< Node>& msg, oratext *uri, oratext *local) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
uri |
取得する要素の名前空間URI |
local |
取得する要素のローカル名 |
戻り値
(Node*) 指定した要素へのポインタ。
SOAPヘッダー要素からmustUnderstand
属性を取得します。
構文
boolean getMustUnderstand( ElementRef< Node>& elem) throw (SoapException);
パラメータ | 説明 |
---|---|
elem |
SOAPヘッダー要素 |
戻り値
(boolean) mustUnderstand
属性の値。
Fault
要素の理由の数を判別します。Fault
がない場合、0
を戻します。
構文
ub4 getReasonNum( DocumentRef< Node>& msg) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
戻り値
(up4) Fault要素の理由の数。
特定のインデックスを持つ理由の言語を戻します。
構文
oratext* getReasonLang( DocumentRef< Node>& msg, ub4 idx) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
idx |
フォルト理由のインデックス |
戻り値
(oratext *) プロパティ値またはNULL
。
SOAPヘッダー要素からロールを取得します。
構文
SoapRole getRole( ElementRef< Node>& elem) throw (SoapException);
パラメータ | 説明 |
---|---|
elem |
ヘッダー要素に対する参照 |
戻り値
(SoapRole) ヘッダー要素のロール。
SOAPメッセージにフォルト・オブジェクトが含まれているかどうかを判別します。
構文
boolean hasFault( DocumentRef< Node>& msg) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
戻り値
(boolean) フォルトがある場合はTRUE
、それ以外はFALSE
。
SOAPメッセージにフォルトを設定します。
構文
void setFault( DocumentRef< Node>& msg, oratext *node, oratext *code, oratext *reason, oratext *lang, oratext *role, ElementRef< Node>& detail) throw (SoapException);
パラメータ | 説明 |
---|---|
msg |
SOAPメッセージ |
node |
フォルトが発生したSOAPノードのURI。 |
code |
フォルト・コード |
reason |
可読的なフォルト理由 |
lang |
言語 |
role |
ロールを示すURI。バージョン1.2ではRole(ロール)、バージョン1.1では使用されていません。 |
detail |
ユーザー定義の要素 |
SOAPヘッダー要素にmustUnderstand
属性を設定します。
構文
void setMustUnderstand( ElementRef< Node>& elem, boolean mustUnderstand) throw (SoapException);
パラメータ | 説明 |
---|---|
elem |
SOAPヘッダー要素 |
mustUnderstand |
mustUnderstand の値(TRUE またはFALSE ) |
SOAPヘッダー要素にロールを設定します。
構文
void setRole( ElementRef< Node>& elem, SoapRole role) throw (SoapException);
パラメータ | 説明 |
---|---|
elem |
ヘッダー要素に対する参照 |
role |
ロール値 |