1. XML C++ APIリファレンス
  2. C++用のSOAP APIパッケージ

6 C++用のSOAP APIパッケージ

W3Cの定義によると「SOAPは、非集中の分散環境で情報を交換するための軽量プロトコルです。XMLベースのプロトコルで、3つの部分から構成されています。メッセージ中にあるものとその処理方法を記述するためのフレームワークを定義するエンベロープ、アプリケーションで定義されるデータ型のインスタンスを表現するための一連のエンコーディング・ルール、リモート・プロシージャ・コールとレスポンスを表現するための規則です。」

SOAPメッセージの構造は次のとおりです。

[SOAP message (XML document)
   [SOAP envelope
      [SOAP header?
            element*
      ]
      [SOAP body
           (element* | Fault)?
      ]
   ]
]

Oracle C++でのSOAPインタフェースの実装には、SOAPのデータ型、SoapExceptionメソッド、ConnectRefメソッド、MsgFactoryメソッドが含まれます。

関連項目:

Oracle XML Developer's Kitプログラマーズ・ガイド

SOAPのデータ型

表6-1にSOAP パッケージのデータ型の概要を示します。

表6-1 データ型の概要: SOAPパッケージ

データ型 説明

SoapExceptionCode

SOAPに関連する例外コードを定義します。

SoapBinding

SOAP接続のためのバインディングを定義します。

SoapRole

SOAPノードのロールを定義します。

SoapExceptionCode

SOAPに関連する例外コードを定義します。

typedef enum SoapExceptionCode {
   SOAP_UNDEFINED_ERR       = 0,
   SOAP_OTHER_ERR           = 1} SoapExceptionCode;

SoapBinding

SOAP接続のためのバインディングを定義します。現在選択できるのはHTTPのみです。

typedef enum SoapBinding {
   BIND_NONE  = 0,  /* none */
   BIND_HTTP  = 1   /* HTTP */ } SoapBinding;

SoapRole

SOAPノードのロールを定義します。

typedef enum SoapRole {
   ROLE_UNSET = 0,  /* not specified */
   ROLE_NONE  = 1,  /* "none" */
   ROLE_NEXT  = 2,  /* "next" */
   ROLE_ULT   = 3   /* "ultimateReceiver" */ } SoapRole;

SoapExceptionインタフェース

表6-2にSoapExceptionインタフェースで使用できるメソッドの概要を示します。

表6-2 SoapExceptionインタフェースの概要

データ型 説明

getCode()

例外に埋め込まれたOracle XMLエラー・コードを取得します。

getMessage()

Oracle XMLエラー・メッセージを取得します。

getMesLang()

エラー・メッセージの現在の言語エンコーディングを取得します。

getSoapCode()

例外に埋め込まれたSOAP例外コードを取得します。

getCode()

例外に埋め込まれたOracle XMLエラー・コードを取得します。これはXMLExceptionから継承された仮想メンバー関数です。

構文

virtual unsigned getCode() const = 0;

戻り値

(unsigned) 数値のエラー・コード(正常に終了した場合は0)。

getMessage()

Oracle XMLエラー・メッセージを取得します。XMLExceptionから継承された仮想メンバー関数です。

構文

virtual oratext* getMessage() const = 0;

戻り値

(oratext *)エラー・メッセージ

getMesLang()

エラー・メッセージの現在の言語エンコーディングを取得します。XMLExceptionから継承された仮想メンバー関数です。

構文

virtual oratext* getMesLang() const = 0;

戻り値

(oratext*) エラー・メッセージの現在の言語(エンコーディング)。

getSoapCode()

例外に埋め込まれたSOAP例外コードを取得します。これは、SOAP API例外コードを戻す、実装で定義済のメンバー関数のプロトタイプを定義する仮想メンバー関数です。

構文

virtual SoapExceptionCode getSoapCode() const = 0;

戻り値

(SoapExceptionCode)例外コード

ConnectRefインタフェース

表6-3に、使用できるConnectRefインタフェースのメソッドの概要を示します。

表6-3 ConnectRefインタフェースの概要

データ型 説明

~ConnectRef()

SOAP接続オブジェクトを破棄します。

call()

SOAPメッセージを送信し、レスポンスを待機します。

~ConnectRef()

デストラクタです。SOAP接続オブジェクトを破棄し、関連付けられていたリソースをすべて解放します。

構文

~ConnectRef() throw (SoapException);

call()

SOAPメッセージを送信し、レスポンスを待機します。

構文

DocumentRef< Node>* call( 
   DocumentRef< Node>& msg) throw (SoapException);
パラメータ 説明 
msg

送信するSOAPメッセージ

戻り値

(DocumentRef)戻されるメッセージ

MsgFactoryインタフェース

表6-4にMsgFactoryインタフェースで使用できるメソッドの概要を示します。

表6-4 MsgFactoryインタフェースの概要

データ型 説明

~MsgFactory()

SOAPメッセージ・ファクトリ・インスタンスを破棄します。

MsgFactory()

SOAPメッセージ・ファクトリ・インスタンスを作成して戻します。

addBodyElement()

SOAPメッセージの本文に要素を追加します。

addFaultReason()

他のフォルト原因を追加します。

addHeaderElement()

SOAPヘッダーに要素を追加します。

createConnection()

SOAP接続を作成します。

createMessage()

空のSOAPメッセージを作成して戻します。

destroyMessage()

SOAPメッセージを破棄します。

getBody()

SOAPメッセージのエンベロープ本文を戻します。

getBodyElement()

SOAP本文から要素を取得します。

getEnvelope()

SOAPパートのエンベロープを戻します。

getFault()

フォルトのコード、理由および詳細を戻します。

getHeader()

SOAPメッセージのエンベロープ・ヘッダーを戻します。

getHeaderElement()

SOAPヘッダーから要素を取得します。

getMustUnderstand()

SOAPヘッダー要素からmustUnderstand属性を取得します。

getReasonNum()

Fault要素の理由の数を取得します。

getReasonLang()

特定のインデックスを持つ理由の言語を取得します。

getRole()

SOAPヘッダー要素からロールを取得します。

hasFault()

SOAPメッセージにフォルト・オブジェクトが含まれているかどうかを判別します。

setFault()

SOAPメッセージにフォルトを設定します。

setMustUnderstand()

SOAPヘッダー要素にmustUnderstand属性を設定します。

setRole()

SOAPヘッダー要素にロールを設定します。

~MsgFactory()

デストラクタです。SOAPメッセージ・ファクトリを破棄します。割り当てられたメモリーはすべて解放され、接続はすべて閉じられます。

構文

~MsgFactory() throw (SoapException);

MsgFactory()

SOAPメッセージ・ファクトリ・インスタンスを作成して戻します。

構文

MsgFactory( 
   Context* ctx_ptr) throw (SoapException);
パラメータ 説明 
ctx_ptr

TContextオブジェクト

戻り値

(MsgFactory)オブジェクト

addBodyElement()

SOAPメッセージの本文に要素を追加します。

構文

Node* addBodyElement( DocumentRef< Node>& msg,
   oratext *qname,
   oratext *uri) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ

 
qname

追加する要素のQName 

uri

追加する要素の名前空間URI

戻り値

(Node*) 作成された要素へのポインタ。

addFaultReason()

他のフォルト原因を追加します。同じ理由のテキストを別の言語で提供できます。フォルトが作成されると、そのときにプライマリ言語と理由が追加されます。この関数は、その理由の翻訳を追加するのに使用します。

構文

void addFaultReason( 
   DocumentRef< Node>& msg,
   oratext *reason, 
   oratext *lang) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ

 
reason

可読的なフォルト理由

 
lang

理由の言語

addHeaderElement()

SOAPヘッダーに要素を追加します。

構文

Node* addHeaderElement( 
   DocumentRef< Node>& msg,
   oratext *qname, oratext *uri) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ

 
qname

追加する要素のQName 

uri

追加する要素の名前空間URI

戻り値

(Node*) 作成された要素へのポインタ。

createConnection()

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)接続オブジェクト

createMessage()

空のSOAPメッセージを作成して戻します。不要になった場合、参照オブジェクトはユーザーが明示的に削除する必要があります。

構文

DocumentRef< Node>* CreateMessage() throw (SoapException);

戻り値

(DocumentRef*) SOAPメッセージ、または例外。

destroyMessage()

SOAPメッセージを破棄します。

構文

void destroyMessage(
   DocumentRef< Node>& msg) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ。

getBody()

SOAPメッセージのエンベロープ本文を、本文の要素ノードへのポインタとして戻します。

構文

Node* getBody( 
   DocumentRef<Node>& msg) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ

戻り値

(Node*) SOAPメッセージのエンベロープ本文へのポインタ。

getBodyElement()

SOAP本文から要素を、要素ノードへのポインタとして取得します。

構文

Node* getBodyElement(
   DocumentRef< Node>& msg,
   oratext *uri,
   oratext *local) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ

 
uri

追加する要素の名前空間URI

 
local

取得する要素のローカル名

戻り値

(Node*) 指定した要素へのポインタ。

getEnvelope()

SOAPパートのエンベロープを、エンベロープ要素ノードへのポインタとして戻します。

構文

Node* getEnvelope( 
   DocumentRef<Node>& msg) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ

戻り値

(Node*) SOAPメッセージのエンベロープへのポインタ。

getFault()

フォルトのコード、理由および詳細を、ユーザー変数を介して戻します。不要なパートには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) 詳細へのポインタ。

getHeader()

SOAPメッセージのエンベロープ・ヘッダーを、ヘッダーの要素ノードへのポインタとして戻します。

構文

Node* getHeader( 
   DocumentRef< Node>& msg) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ

戻り値

(Node*) SOAPメッセージのエンベロープ・ヘッダーへのポインタ。

getHeaderElement()

SOAPヘッダーから要素を、要素ノードへのポインタとして取得します。

構文

Node* getHeaderElement( 
   DocumentRef< Node>& msg,
   oratext *uri, 
   oratext *local) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ

 
uri

取得する要素の名前空間URI

 
local

取得する要素のローカル名

戻り値

(Node*) 指定した要素へのポインタ。

getMustUnderstand()

SOAPヘッダー要素からmustUnderstand属性を取得します。

構文

boolean getMustUnderstand( 
   ElementRef< Node>& elem) throw (SoapException);
パラメータ 説明 
elem

SOAPヘッダー要素

戻り値

(boolean) mustUnderstand属性の値。

getReasonNum()

Fault要素の理由の数を判別します。Faultがない場合、0を戻します。

構文

ub4 getReasonNum(
   DocumentRef< Node>& msg) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ

戻り値

(up4) Fault要素の理由の数。

getReasonLang()

特定のインデックスを持つ理由の言語を戻します。

構文

oratext* getReasonLang( 
   DocumentRef< Node>& msg,
   ub4 idx) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ

 
idx

フォルト理由のインデックス

戻り値

(oratext *) プロパティ値またはNULL。

getRole()

SOAPヘッダー要素からロールを取得します。

構文

SoapRole getRole( 
   ElementRef< Node>& elem) throw (SoapException);
パラメータ 説明 
elem

ヘッダー要素に対する参照

戻り値

(SoapRole) ヘッダー要素のロール。

hasFault()

SOAPメッセージにフォルト・オブジェクトが含まれているかどうかを判別します。

構文

boolean hasFault( 
   DocumentRef< Node>& msg) throw (SoapException);
パラメータ 説明 
msg

SOAPメッセージ

戻り値

(boolean) フォルトがある場合はTRUE、それ以外はFALSE。

setFault()

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

ユーザー定義の要素

setMustUnderstand()

SOAPヘッダー要素にmustUnderstand属性を設定します。

構文

void setMustUnderstand( 
   ElementRef< Node>& elem,
   boolean mustUnderstand) throw (SoapException);
パラメータ 説明 
elem

SOAPヘッダー要素

 
mustUnderstand

mustUnderstandの値(TRUE またはFALSE)

setRole()

SOAPヘッダー要素にロールを設定します。

構文

void setRole( 
   ElementRef< Node>& elem, 
   SoapRole role) throw (SoapException);
パラメータ 説明 
elem

ヘッダー要素に対する参照

 
role

ロール値