4.2.1 dc_clt_cltin_s − クライアントユーザの認証要求
(1) 形式
(a) TP1/Client/Wの場合
■ _s付き関数
#include <dcvclt.h> DCLONG dc_clt_cltin_s(HWND hWnd, DCCLT_ID *cltid, char *defpath, char *target_host, char *logname, char *passwd, char *set_host, DCLONG flags)
■ _s無し関数
#include <dcvclt.h> int dc_clt_cltin(char *target_host, char *logname, char *passwd, char *set_host, DCLONG flags)
(b) TP1/Client/Pの場合
■ _s付き関数
#include <dcvclt.h> DCLONG dc_clt_cltin_s(HWND hWnd, DCCLT_ID CLTFAR *cltid, char CLTFAR *defpath, char CLTFAR *target_host, char CLTFAR *logname, char CLTFAR *passwd, char CLTFAR *set_host, DCLONG flags)
■ _s無し関数
#include <dcvclt.h> int dc_clt_cltin(char CLTFAR *target_host, char CLTFAR *logname, char CLTFAR *passwd, char CLTFAR *set_host, DCLONG flags)
(2) 機能
指定された窓口となるTP1/Serverに対して,ログイン名で指定されたクライアントユーザの認証を要求します。
ユーザ認証を抑止する場合でも,dc_clt_cltin_s関数は必ず実行してください。
(3) UAPで値を設定する引数
-
hWnd
NULLを指定します。
-
cltid
クライアントID(ヘッダファイルdcvclt.hで定義されていて,型はDCCLT_ID)を受け取る領域へのポインタを指定します。
クライアントユーザの認証が正常に終了すると,指定した領域にクライアントIDが設定されます。設定されたクライアントIDは,dc_clt_cltout_s関数を呼び出すまで破壊してはなりません。
ここで取得したクライアントIDは,この関数を発行したスレッド内でしか使用できません。別のスレッドに引き渡して使用(dc_rpc_call_s関数などを発行するなど)した場合の動作は保証しません。
-
defpath
クライアント環境定義ファイルへのパス名を指定します。パス名には完全パス,またはカレントドライブ・ディレクトリからの相対パスが指定できます。パス名を指定した場合のファイルの読み込み順序を次に示します。
-
TP1/Client/Pの場合
クライアント環境定義ファイルの読み込み順序は次のとおりです。
1.WindowsディレクトリのBETRAN.INIファイル
2.引数defpathに指定したクライアント環境定義ファイル
定義は,クライアント環境定義ファイルおよびBETRAN.INIファイルのどちらのファイルに指定しても有効です。
両方のファイルに同じ定義を異なる値で指定した場合は,クライアント環境定義ファイルに指定した値が有効となります。
クライアント環境定義ファイルおよびBETRAN.INIファイルのどちらにも指定がない場合は,デフォルト値で動作します。
-
TP1/Client/Wの場合
環境変数に指定されている定義は,すべて無効となります。引数defpathに指定したクライアント環境定義ファイルに指定されていない定義はデフォルト値で動作します。
また,引数defpathの先頭にNULLを指定することでパス名を省略できます。省略時の動作を次に示します。
-
TP1/Client/Pの場合
WindowsディレクトリのBETRAN.INIファイルをクライアント環境定義ファイルとして動作します。BETRAN.INIファイルがない場合,または定義ファイルの内容が不正な場合はデフォルト値で動作します。
-
TP1/Client/Wの場合
環境変数の指定で動作します。環境変数が指定されていない場合は,デフォルト値で動作します。
引数defpathに指定したクライアント環境定義ファイルがない場合,または定義ファイルの内容が不正な場合の動作を次に示します。
-
TP1/Client/Pの場合
WindowsディレクトリのBETRAN.INIファイルをクライアント環境定義ファイルとして動作します。BETRAN.INIファイルがない場合,または定義ファイルの内容が不正な場合は,デフォルト値で動作します。
-
TP1/Client/Wの場合
デフォルト値で動作します。環境変数の指定は無効となります。
-
-
target_host
認証要求を実行する時に窓口となるTP1/Serverのホスト名およびポート番号を指定します。複数の窓口となるTP1/Serverを指定できます(区切り文字は','を使用)。
ホスト名として指定できる長さは,63文字※までです。ホスト名を複数指定する場合,引数target_hostに指定できる長さ(ポート番号なども含む)は,255文字※までです。
- 形式
-
ホスト名〔:ポート番号〕〔,ホスト名〔:ポート番号〕,…〕
・ホスト名 〜〈文字列〉
・ポート番号 〜〈符号なし整数〉((5001〜65535))
区切り文字','の後ろ以外は空白文字(スペースまたはタブ)を入れないでください。
ホスト名として,10進ドット記法のIPアドレスを指定することもできます。
ポート番号省略時は,クライアント環境定義DCNAMPORTの値を仮定します。
引数target_hostにTP1/Serverを二つ以上指定し,窓口となるTP1/Serverの障害を検出した場合,クライアント環境定義DCHOSTSELECTがNのとき,現在窓口となっているTP1/Serverの次のTP1/Serverを参照して切り替えを試みます。クライアント環境定義DCHOSTSELECTがYのとき,障害を検出したTP1/Serverを除いて,窓口となるTP1/Serverをランダムに選択して切り替えを試みます。
NULLが指定されていた場合は,クライアント環境定義DCHOSTを参照します。ただし,引数target_hostにNULLが指定されていて,DCHOSTが設定されていなかった場合は,ブロードキャストを行い,窓口となるTP1/Serverを決定します。TP1/Client/Pでブロードキャストを行う場合,hostsファイルにブロードキャストアドレスを指定する必要があります(ホスト名はbroadcastとしてください)。指定がなかった場合,dc_clt_cltin_s関数はDCCLTER_SYSERRでエラーリターンします。
- 注※
-
クライアント環境定義DCCLTOPTIONに00000008を指定した場合,ホスト名として指定できる長さは,255文字までです。ホスト名を複数指定する場合,引数target_hostに指定できる長さ(ポート番号なども含む)は1,023文字までとなります。
-
logname
クライアントユーザのログイン名を指定します。ログイン名として指定できる長さは,15文字までです。TP1/Server以外のサーバと通信する場合は,NULL以外の任意の値を指定します。NULLを指定した場合,関数はエラーリターンします。
-
passwd
lognameで指定したログイン名に対するパスワードを指定します。パスワードとして指定できる長さは,15文字までです。パスワードが設定されていない場合は,NULLを指定します。
-
set_host
実際に認証要求をしたホストのホスト名を格納する64バイト※の領域へのポインタを指定します。NULLが指定された場合は,ホスト名を格納しません。
- 注※
-
クライアント環境定義DCCLTOPTIONに00000008を指定した場合,64バイトではなく,256バイトになります。
-
flags
リモートAPI機能を使用するためにユーザ認証を抑止する場合は,DCCLT_NO_AUTHENTを指定します。ユーザ認証を抑止しない場合は,DCNOFLAGSを指定します。
(4) 値が返される引数
-
cltid
クライアントIDが返されます。
-
set_host
ユーザ認証したサーバのホスト名(または10進ドット記法のIPアドレス)が返されます。ユーザ認証を抑止した場合は,返されません。
(5) リターン値
リターン値 |
数値 (10進数) |
意味 |
---|---|---|
DC_OK |
0 |
正常終了しました。 |
DCCLTER_INVALID_ARGS |
-2501 |
引数が誤っています。 |
DCCLTER_PROTO |
-2502 |
すでにdc_clt_cltin関数が実行されています。dc_clt_cltin_s関数実行時は,このリターン値は返りません。 |
DCCLTER_FATAL |
-2503 |
通信路の初期化に失敗しました。または,クライアント環境定義の指定が誤っています。 |
DCCLTER_NO_BUFS |
-2504 |
必要なバッファが確保できませんでした。または,リソース不足が発生しました。 |
DCCLTER_NET_DOWN |
-2506 |
通信障害が発生しました。 |
DCCLTER_OLTF_NOT_UP |
-2515 |
設定したサービスがあるノードのOpenTP1が起動されていません。 |
DCCLTER_SYSERR |
-2518 |
システムエラーが発生しました。 |
DCCLTER_REJECT |
-2527 |
指定されたログイン名が対象とするホストに登録されていないか,またはパスワードが一致しません。または,ユーザ認証機能をサポートしていないOpenTP1サーバである可能性があります。システム共通定義client_uid_checkの指定が正しいか見直してください。 |
DCCLTER_PORT_IN_USE |
-2547 |
指定したポート番号は使用されています。または,OSが自動的に割り当てるポート番号が不足しています。 |
(6) 注意事項
-
TP1/Server側がUNIXで,機密保護機構によって暗号化パスワードフィールドに*がセットされている場合,ユーザ認証を受けられないのでご注意ください。この場合,dc_clt_cltin_s関数はDCCLTER_REJECTでエラーリターンします。
-
dc_clt_cltin_s関数がエラーリターンした場合,引数に指定したcltidは無効となるため,cltidを指定してTP1/Clientの関数を発行できません。再度,dc_clt_cltin_s関数から実行し直してください。
-
引数set_hostに値を受け取る場合は,64バイト※以上の領域を指定してください。領域が64バイト※未満の場合,TP1/Client内部の処理で領域破壊を起こすおそれがあります。なお,ユーザ認証を抑止した場合,値は格納されません。
- 注※
-
クライアント環境定義DCCLTOPTIONに00000008を指定した場合,64バイトではなく,256バイトになります。
-
TP1/Clientでは,dc_clt_cltin_s関数の呼び出しごとにクライアント環境定義を定義できます。dc_clt_cltin_s関数の呼び出しごとにクライアント環境定義を定義するには,dc_clt_cltin_s関数の呼び出しごとに,異なるファイルをクライアント環境定義ファイルとして作成して,そのファイル名をdc_clt_cltin_s関数の引数defpathに指定してください。
-
リターン値DCCLTER_SYSERRが戻る場合,CUPを終了してから開始し直してください。