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
メソッドが含まれます。
SOAPのデータ型
表6-1にSOAP
パッケージのデータ型の概要を示します。
表6-1 データ型の概要: SOAPパッケージ
データ型 | 説明 |
---|---|
SOAPに関連する例外コードを定義します。 |
|
SOAP接続のためのバインディングを定義します。 |
|
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;
SoapExceptionインタフェース
表6-2にSoapExceptionインタフェースで使用できるメソッドの概要を示します。
表6-2 SoapExceptionインタフェースの概要
データ型 | 説明 |
---|---|
例外に埋め込まれたOracle XMLエラー・コードを取得します。 |
|
Oracle XMLエラー・メッセージを取得します。 |
|
エラー・メッセージの現在の言語エンコーディングを取得します。 |
|
例外に埋め込まれた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*) エラー・メッセージの現在の言語(エンコーディング)。
ConnectRefインタフェース
表6-3に、使用できるConnectRefインタフェースのメソッドの概要を示します。
表6-3 ConnectRefインタフェースの概要
データ型 | 説明 |
---|---|
SOAP接続オブジェクトを破棄します。 |
|
SOAPメッセージを送信し、レスポンスを待機します。 |
~ConnectRef()
デストラクタです。SOAP接続オブジェクトを破棄し、関連付けられていたリソースをすべて解放します。
構文
~ConnectRef() throw (SoapException);
MsgFactoryインタフェース
表6-4にMsgFactoryインタフェースで使用できるメソッドの概要を示します。
表6-4 MsgFactoryインタフェースの概要
データ型 | 説明 |
---|---|
SOAPメッセージ・ファクトリ・インスタンスを破棄します。 |
|
SOAPメッセージ・ファクトリ・インスタンスを作成して戻します。 |
|
SOAPメッセージの本文に要素を追加します。 |
|
他のフォルト原因を追加します。 |
|
SOAPヘッダーに要素を追加します。 |
|
SOAP接続を作成します。 |
|
空のSOAPメッセージを作成して戻します。 |
|
SOAPメッセージを破棄します。 |
|
SOAPメッセージのエンベロープ本文を戻します。 |
|
SOAP本文から要素を取得します。 |
|
SOAPパートのエンベロープを戻します。 |
|
フォルトのコード、理由および詳細を戻します。 |
|
SOAPメッセージのエンベロープ・ヘッダーを戻します。 |
|
SOAPヘッダーから要素を取得します。 |
|
SOAPヘッダー要素から |
|
|
|
特定のインデックスを持つ理由の言語を取得します。 |
|
SOAPヘッダー要素からロールを取得します。 |
|
SOAPメッセージにフォルト・オブジェクトが含まれているかどうかを判別します。 |
|
SOAPメッセージにフォルトを設定します。 |
|
SOAPヘッダー要素に |
|
SOAPヘッダー要素にロールを設定します。 |
~MsgFactory()
デストラクタです。SOAPメッセージ・ファクトリを破棄します。割り当てられたメモリーはすべて解放され、接続はすべて閉じられます。
構文
~MsgFactory() throw (SoapException);
MsgFactory()
SOAPメッセージ・ファクトリ・インスタンスを作成して戻します。
構文
MsgFactory( Context* ctx_ptr) throw (SoapException);
パラメータ | 説明 |
---|---|
ctx_ptr |
|
戻り値
(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 |
データ・バッファ(バッファの割当てを受けるときは |
bufsiz |
データ・バッファのサイズ(デフォルトのサイズは0) |
msgbuf |
メッセージ・バッファ(バッファの割当てを受けるときは |
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 |
理由に指定する言語または |
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 |
|