9.4.3 電文情報設定UOC
機能
電文情報設定UOCは、システム分析支援アダプタの処理に必要な電文情報を指定するUOCです。
形式
ANSI C、C++の形式
#include <esplg_uoc.h> ESLONG uoc_func(struct es_plg_uoc_info *parm)
「uoc_func」部分には、システム内で一意の名称を指定してください。
説明
電文入力時に呼び出されるUOCです。
電文情報設定UOCでは、次の情報を設定する必要があります。
-
ペアリングキー
-
要求電文種別（クライアントからサーバへの電文の場合）
- ペアリングキーの判定
-
UOCでは、要求電文と応答電文を関連づけるためのペアリングキーを指定する必要があります。
また、要求電文を電文組立UOCで組立後、framework_definition定義の-t reply_watchtimeオペランドに指定した時間経過すると応答待ちタイムアウトとなり、要求電文を破棄します。タイムアウト後に応答電文を受信した場合、応答電文を破棄します。
- 要求電文種別の判定
-
UOCでは、要求電文に対して、応答を待ち合わせる必要のある要求電文（同期要求電文）か、待ち合わせる必要がない要求電文（非応答要求電文）かを指定する必要があります。
パラメタの内容
es_plg_uoc_infoのパラメタ内容
typedef struct es_plg_uoc_info {
ESULONG run_mode; ………………… 実行形態
ESULONG protocol; ………………… プロトコル種別
unsigned char msgtype; ………………… 電文種別
unsigned char reqtype; ………………… 要求電文種別
char reserve[2]; ……………… 予備領域
ESULONG error_flg; ……………… エラー情報
ESCOM_IPADDR src_ip; ……………… 送信元IPアドレス
ESCOM_IPADDR dst_ip; ……………… 送信先IPアドレス
unsigned short src_port; ………………… 送信元ポート番号
unsigned short dst_port; ………………… 送信先ポート番号
char reserve2[4]; …………… 予備領域
ESCOM_AREA usr_tel_area; ………… 電文単位ユーザ領域
char usr_tel_area_state; ………… 電文単位ユーザ領域の状態
char reserve3[7]; …………… 予備領域
ESCOM_AREA usr_con_area; ……… コネクション単位ユーザ領域
char usr_con_area_state; ……… コネクション単位ユーザ領域の状態
char reserve4[7]; …………… 予備領域
ESCOM_AREA telegram; …… 電文情報
ESPLG_UOC_TELSIZE telegram_size; … 電文サイズ
char client_id[16]; ………… クライアント識別子
ESLONG rtn_detail; ………… 詳細エラーコード
char reserve5[4]; …………… 予備領域
char key[64]; ……………… ペアリングキー
void *protoinf; ……………… プロトコル情報（参照できません）
ESULONG abort_code; …………… 強制停止理由コード
char reserve6[4]; …………… 予備領域
} ESPLG_UOC_INFO;
es_com_ipaddr（ESCOM_IPADDR）のパラメタ内容
typedef union es_com_ipaddr{
ESCOM_IPV4 ipv4; ……………… IPアドレス（IPv4）
char reserve[16]; ……………… 予備領域
} ESCOM_IPADDR;
es_com_ipv4（ESCOM_IPV4）のパラメタ内容
typedef struct es_com_ipv4 {
char reserve[12]; ……………… 予備領域
char ip[4]; ……………… IPアドレス（IPv4）
} ESCOM_IPV4;
es_com_area（ESCOM_AREA）のパラメタ内容
typedef struct es_com_area {
ESULONG size; ……………… 領域サイズ
char reserve[4]; ……………… 予備領域
char *data; ……………… 領域先頭アドレス
} ESCOM_AREA;
ESPLG_UOC_TELSIZEのパラメタ内容
typedef union {
ESPLG_UOC_HTTPSIZE http_size; …………HTTPプロトコルのサイズ格納領域
ESPLG_UOC_TCPSIZE tcp_size; …………TCPプロトコルのサイズ格納領域
} ESPLG_UOC_TELSIZE;
ESPLG_UOC_HTTPSIZEのパラメタ内容
typedef struct es_plg_uoc_httpsize{
ESULONG header_size; …………HTTPヘッダ部サイズ
ESULONG body_size; …………HTTPボディ部サイズ
} ESPLG_UOC_HTTPSIZE;
ESPLG_UOC_TCPSIZEのパラメタ内容
typedef struct es_plg_uoc_tcpsize{
ESULONG size; …………電文サイズ
char reserve[4];
} ESPLG_UOC_TCPSIZE;
システム検証支援基盤が設定するパラメタ項目
- run_mode
-
システム分析支援アダプタの実行形態を設定します。
ESFRW_RUNMODE_CREATE_A：システム分析支援リアルタイムモニタ連携
- protocol
-
プロトコル種別を設定します。
ESFRW_PROT_TCP：TCP
- msgtype
-
電文種別を設定します。
ESFRW_MSGTYPE_REQUEST_PRO：要求電文
ESFRW_MSGTYPE_RESPONSE_PRO：応答電文
- reqtype
-
ユーザが設定する値です。
システム検証支援はデフォルト値 ESFRW_MSGFORM_SYNC_ANSWER（同期応答型）を設定します。
- error_flg
-
システム検証支援が検知したエラー有無、およびエラー内容を設定します。次のどれかとなります。
ESFRW_ERROR_NONE：エラーなし
ESFRW_ERROR_RECV_CON：コネクション切断による受信・不可
ESFRW_ERROR_RECV_LOST：パケットロスト発生
ESFRW_ERROR_BUILD_TIMEOUT：電文組立中の後続パケット待ちタイムアウト
ESFRW_ERROR_RECV_TIMEOUT：応答待ちタイムアウトによる受信不可
設定値がESFRW_ERROR_NONE以外の場合、以下に示すパラメタだけ参照・設定可能です。
-
参照可能なパラメタ
run_mode
protocol
msgtype
reqtype
src_ip
dst_ip
src_port
dst_port
-
設定可能なパラメタ
abort_code
上記以外のパラメタは参照・設定しないでください。
-
- src_ip
-
電文の送信元のIPアドレスを設定します。※
- dst_ip
-
電文の送信先のIPアドレスを設定します。※
- src_port
-
電文の送信元のポート番号をホストバイトオーダーで設定します。
- dst_port
-
電文の送信先のポート番号をホストバイトオーダーで設定します。
- usr_tel_area
-
電文単位に共有するユーザ領域を設定します。
各メンバには以下の値が設定されています。
-
size
電文単位ユーザ領域のサイズを設定します。
-
data
電文単位ユーザ領域の先頭アドレスを設定します。
-
- usr_tel_area_state
-
電文単位ユーザ領域の状態を設定します。電文単位ユーザ領域の状態は電文単位ユーザ領域の領域サイズが0以外のときに設定します。
-
ESFRW_CONTST_NEW
新規に割り当てられた領域であることを示します。
-
ESFRW_CONTST_RENEW
処理済みとなった電文のユーザ領域が再割り当てされて、通知されたことを示します。ユーザ領域内には現在処理している電文とは無関係の情報が設定されている場合があります。必要に応じて、ユーザ領域に残っている必要な情報の退避、および初期化などを実施して使用してください。
-
ESFRW_CONTST_CONTINUE
当該電文のユーザ領域として、UOCに通知済みの領域であることを示します。以前に通知された際に情報を設定していれば、参照することができます。
-
- usr_con_area
-
コネクション単位で共有するユーザ領域を設定します。
各メンバには以下の値が設定されています。
-
size
コネクション単位ユーザ領域のサイズを設定します。
-
data
コネクション単位ユーザ領域の先頭アドレスを設定します。
-
- usr_con_area_state
-
コネクション単位ユーザ領域の状態を設定します。コネクション単位ユーザ領域の状態はコネクション単位ユーザ領域の領域サイズが0以外のときに設定します。
-
ESFRW_CONTST_NEW
新規に割り当てられた領域であることを示します。
-
ESFRW_CONTST_RENEW
切断されたコネクションのユーザ領域が再割り当てされて、通知されたことを示します。ユーザ領域内には現在のコネクションとは無関係の情報が設定されている場合があります。必要に応じて、ユーザ領域に残っている必要な情報の退避、および初期化などを実施して使用してください。
-
ESFRW_CONTST_CONTINUE
当該コネクションのユーザ領域として、UOCに通知済みの領域であることを示します。以前に通知された際に情報を設定していれば、参照することができます。
-
- telegram
-
入力電文に関する情報を設定します。
各メンバには以下の値が設定されています。
-
size
入力電文のサイズを設定します。
-
data
入力電文の先頭アドレスを設定します。
-
- telegram_size
-
プロトコル種別ごとの入力電文のヘッダ領域を設定します。
- client_id
-
コネクションごとに一意となる値を設定します。
- key
-
ユーザが設定する値です。
デフォルト値として、コネクションごとに一意となる値を設定します。このデフォルト値を使用した場合、同一コネクションの要求電文と応答電文がペアリングされます。
- 注※
IPアドレスは、次に示す形式で設定します。
IPv4の場合
例） 送信元IPが172.165.112.20の場合
![[図データ]](GRAPHICS/F0000005.GIF)
ユーザが設定するパラメタ項目
- reqtype
-
要求電文の種別を指定できます。指定できる電文種別は次のとおりです。
-
ESFRW_MSGFORM_SYNC_ANSWER:同期応答型
-
ESFRW_MSGFORM_NOANSWER:非応答型
デフォルトでは ESFRW_MSGFORM_SYNC_ANSWERを指定しています。
次の条件を満たす場合に設定してください。
-
要求電文
条件を満たさない場合、設定する必要はありません。
-
- client_id
-
設定しないでください。
- rtn_detail
-
詳細コードを-2147483648 〜 2147483647の範囲で設定できます。このコードはUOCがES_UOC_NGをリターンしたときにシステム検証支援に返されます。システム検証支援は詳細エラーコードをメッセージログファイルに出力します。
- key
-
要求電文と応答電文について、システム内で一意となる同じキーを指定してください。
次の条件のどれかに該当する場合、このキーを設定してください。
-
要求電文と応答電文が異なるコネクション
-
複数のクライアントがコネクションを共用してサーバと送受信する
条件を満たさない場合、設定する必要はありません。
-
- abort_code
-
システム検証支援を強制停止する理由を示すコードを0 ～ 4294967295の範囲で設定できます。
このコードはUOCがESPLG_UOC_ABORTをリターンしたときのみ有効です。システム検証支援は強制停止理由コードをKFSE64109-Eメッセージに出力します。
ユーザが設定する項目は、電文のプロトコルとリターン値によって異なります。
ユーザが設定する項目と、電文のプロトコルとリターン値の関係を次に示します。
|
項目 |
TCPのリターン値 |
|||
|---|---|---|---|---|
|
ES_UOC_OK |
ESPLG_UOC_MSG_DESTRUCT |
ES_UOC_NG |
ESPLG_UOC_ABORT |
|
|
要求電文種別 |
○※ |
× |
× |
× |
|
クライアント識別子 |
○ |
× |
× |
× |
|
詳細エラーコード |
× |
× |
○ |
× |
|
ペアリングキー |
○ |
× |
× |
× |
|
強制停止理由コード |
× |
× |
× |
○ |
- （凡例）
-
○：指定可能
×：指定不可（指定値は無視します）
- 注※
-
パケットの電文種別がESFRW_MSGTYPE_REQUEST_PROの場合に有効となります。
リターン値
次のコードでリターン値を設定してください。
- ESPLG_UOC_OK
-
正常に電文情報を設定しました。
- ESPLG_UOC_MSG_DESTRUCT
-
電文を破棄します。
- ESPLG_UOC_ABORT
-
電文を強制停止します。
- ESPLG_UOC_NG
-
電文情報設定時にでエラーが発生しました。電文を破棄します。
- 上記以外
-
指定リターン値以外でリターンした場合、電文を破棄します。
注意事項
-
UOCで設定した値に不正があった場合、システム検証支援はメッセージログを出力し、対象の電文を破棄します。
-
パラメタerror_flgの値によってUOCリターン時の動作が異なります。
error_flgの値
動作
ESFRW_ERROR_NONE
- リターン値ESPLG_UOC_NGでリターンした場合
-
UOCからESPLG_UOC_NGでリターンした場合、システム検証支援はメッセージログを出力し、対象の電文を破棄します。
- リターン値ESPLG_UOC_ABORTでリターンした場合
-
システム検証支援はKFSE64109-Eメッセージを出力し、システム検証支援プロセスを強制停止します。
- UOCパラメタ不正の場合
-
UOCで設定した値に不正があった場合、システム検証支援はメッセージログを出力し、対象の電文を破棄します。
ESFRW_ERROR_NONE以外
- リターン値ESPLG_UOC_OKでリターンした場合
-
システム検証支援は処理を続行します。
- リターン値ESPLG_UOC_ABORTでリターンした場合
-
システム検証支援はKFSE64109-Eメッセージを出力し、システム検証支援プロセスを強制停止します。
- 上記以外の場合
-
システム検証支援は処理を続行します。