doclib\hspinet.txt » Plain Format
------------------------------------------------------------------------------
HSPINET ver3.1 REFERENCE MANUAL HSP : Hot Soup Processor
ＨＳＰ拡張拡張DLLリファレンス copyright 2005 (c) onion software
------------------------------------------------------------------------------
・はじめに
このDLLは、Hot Soup Processor ver3.1以降とともに使用することで、
WindowsのWininet.dllモジュールが持つインターネットアクセス機能を
利用可能にします。
HSPINETを使用することにより、httpによるネット上のファイル取得、
proxyを用いたアクセス、各種ヘッダの設定などを行なうことができます。
また、CRC32、MD5といったファイル内容をチェックするための命令も
用意されています。
HSPINETを使用するためには、Internet Explorer 3.0以降がインストール
されている必要があります。
・使い方の概要
HSPINETを使用する場合は、スクリプトの先頭に必ず「#include "hspinet.as"」
という行を追加してください。以上で、HSPの機能が拡張され、このリファレンスで
説明をしている命令を使用することができるようになります。
まず最初に、試しに付属のサンプルスクリプト(test??.as)を実行してみてください。
拡張された機能の簡単な使用例を見ることができるはずです。
HSPINET.DLLは、大きく「http関連命令」「ftp関連命令」「ファイル関連命令」に
分かれています。
「ファイル関連命令」は、ローカルなファイルに対して処理を行なうためのもので、
MD5、CRC32といったファイルのハッシュ値となる値を取得することができます。
「http関連命令」は、netinit命令によって初期化を行なってから、各種命令で
httpサーバーとの通信を行なっていきます。
http関連命令は、基本的にサーバーからローカルマシンにファイルをダウンロード
してくることが前提になっています。
ファイルのダウンロードには、URL指定とファイル名指定が必要になります。
URL指定では、ダウンロードを行なうファイルを除いたネット上のアドレスを設定
しておきます。たとえば、「http://www.onionsoft.net/hsp/」のような感じです。
その後、netload命令やnetrequest命令、netfileinfo命令などでファイル名を
指定します。たとえば、「index.html」を指定した場合には、先に設定されている
URL指定と合わせて「http://www.onionsoft.net/hsp/index.html」からファイルが
ダウンロードされることになります。
「ftp関連命令」は、netinit命令によって初期化を行なってから、各種命令で
ftpサーバーとの通信を行なうためのものです。ftpサーバーからのダウンロード、
アップロードを含めた多くの機能を持っています。
HSPINET.DLLは、手軽にネット上のファイルをチェックしたり、ダウンロードと
ファイル処理を行なうために用意されたものです。
より高度なネットワーク操作、サポート外のプロトコルを使用する場合には、
HSPSOCK.DLLなどソケット通信を行なってください。
また、現バージョンでは複数のストリームを並行して処理することはできません。
・更新履歴
2007/3/9 ver1.2
ftpopenの第4パラメーターが指定できなかった不具合を修正。
2005/6/29 ver1.1
ftp関連の命令を追加。
2005/5/7 ver1.0
最初のバージョン。
・注意点
HSPINET.DLLは、HSP3.EXEと同時に使用されるプラグインファイルです。
使用するHSPは、ver3.0以上をお使い下さい。ver2.61やそれ以前のHSPには
対応していませんのでご注意下さい。
EXEファイルを作成した場合でも、HSPINET.DLLをEXEファイルと同じディレクトリ
に置かないと動作しません。また、packfileにDLLを追加することはできません。
・著作権および連絡先
ユーザーがHSPを使って作成したオリジナルのソフトウェア(実行ファイル)の
権利は、それを作成したユーザーに属します。
有償・無償を問わずHSPINET.DLLを自由に配布することができ、onion softwareの
著作権表示義務もありません。
ユーザーが作成したオリジナルのソフトウェアに対してonion softwareが著作権を
主張することはありません。
HSPINETプラグインは、onion softwareの著作物です。
onion softwareは本プログラムによって生じた、いかなる損害についても
保証いたしません。自己の責任の範囲で使用してください。
HSPINET.DLLは、Microsoft Visual C++ 7.1でコンパイルされて います。
・命令一覧
netinit ネット接続の初期化
netterm ネット接続の終了
netexec 最小単位の処理を実行
netmode モードの取得
neterror ネットエラー文字列の取得
neturl URLの設定
netdlname ダウンロード名の設定
netproxy プロキシの設定
netagent エージェントの設定
netheader ヘッダ文字列の設定
netrequest httpリクエスト発行
netload httpファイル取得
netfileinfo httpファイル情報取得
netsize ファイル受信サイズの取得
filecrc ファイルのCRC32を取得
filemd5 ファイルのMD5を取得
ftpopen FTPセッションの開始
ftpclose FTPセッションの終了
ftpresult FTP処理結果文字列の取得
ftpdir FTPディレクトリ移動
ftpdirlist FTPディレクトリリスト取得1
ftpdirlist2 FTPディレクトリリスト取得2
ftpcmd FTPコマンドの実行
ftprmdir FTPディレクトリの削除
ftpmkdir FTPディレクトリの作成
ftpget FTPファイル取得
ftpput FTPファイル送信
ftprename FTPファイル名前変更
ftpdelete FTPファイル削除
・http関連命令
Wininet.dllを経由してhttpサーバーにアクセスするための命令セットです。
netinit ネット接続の初期化
Wininet.dllの初期化を行ないます。
net〜で始まる命令を使用する際には、最初に１回だけ必ず実行する
必要があります。実行後に結果がシステム変数statに格納されます。
0ならば正常終了、それ以外はエラーが発生したことを示しています。
netterm ネット接続の終了
Wininet.dllの終了処理を行ないます。
通常、この命令はプログラム終了時に自動的に呼び出されるため、
特にスクリプトに記述する必要はありません。
netexec p1 最小単位の処理を実行
p1 : 処理の結果が代入される変数
最小単位の処理を実行します。
サーバーからの応答待ちや、ダウンロード中など時間のかかる処理を
細かい単位で実行します。
メインプログラムでは、await命令などで細かく待ち時間(ウェイト)を
取りながらnetexec命令を呼び出す必要があります。
例:
; 結果待ちのためのループ
repeat
netexec res
if res : break
await 50
loop
実行後、結果がp1で指定された変数に代入されます。
内容が0の場合は、処理が継続中であることを意味します。
内容が1以上の場合は、処理が正常に終了していることを意味します。
内容がマイナス値の場合は、何らかのエラーが発生したことを
示しています。
statが0以外の値になった場合は、それに応じた処理を適宜
スクリプト側で処理するようにしてください。
netmode p1 モードの取得
p1 : モード値が代入される変数
現在の処理モードを取得します。
p1で指定された変数にモード値が代入されます。
モード値の内容は以下の通りです。
httpリクエストは、INET_MODE_READYの状態で発行するように
してください。
ftpリクエストは、INET_MODE_FTPREADYの状態で発行するように
してください。
ラベル | 値 状態
------------------------------------------------------
INET_MODE_NONE | 0 未初期化の状態
INET_MODE_READY | 1 待機状態
INET_MODE_REQUEST | 2 httpリクエスト受付
INET_MODE_REQSEND | 3 httpリクエスト送信中
INET_MODE_DATAWAIT | 4 httpデータ受信中
INET_MODE_DATAEND | 5 httpデータ受信終了処理中
INET_MODE_INFOREQ | 6 http情報リクエスト送信中
INET_MODE_INFORECV | 7 http情報データ受信中
INET_MODE_FTPREADY | 8 ftp待機状態
INET_MODE_FTPDIR | 9 ftpディレクトリ情報取得中
INET_MODE_FTPREAD | 10 ftpファイル受信中
INET_MODE_FTPWRITE | 11 ftpファイル送信中
INET_MODE_FTPCMD | 12 ftpコマンド送信終了処理中
INET_MODE_FTPRESULT| 13 ftpサーバー返信データ受信中
INET_MODE_ERROR | 14 エラー状態
neterror p1 ネットエラー文字列の取得
p1 : エラー文字列が代入される変数
エラー発生時の詳細を示す文字列を取得します。
p1で指定した変数に、文字列として代入されます。
neturl "URL" URLの設定
"URL" : URLを示す文字列
httpリクエストを行なうURLを設定します。
URLは、ファイル名を除いた形でスキーム名を含めて設定する
必要があります。
「http://www.onionsoft.net/hsp/index.html」の場合は、
「http://www.onionsoft.net/hsp/」までを設定してください。
httpリクエストは必ず、neturl命令によるURL設定を先に
行なっておいてください。neturl命令実行の時点では、
まだhttpリクエストは発行されません。
httpリクエストの発行は、netrequest命令またはnetload命令
によって行なわれます。
netrequest "FileName" httpリクエスト発行
"FileName" : リクエストを行なうファイル名
httpリクエストを行ないます。
先に、neturl命令によりファイル名を除いたURLを指定しておく
必要があります。
netrequest命令でhttpリクエストを発行した後は、netexec命令
により受信処理をスクリプト側で行なう必要があります。
受信処理を自動で行なうためのnetload命令も別途用意されています。
netload "FileName" httpファイル取得
"FileName" : リクエストを行なうファイル名
httpリクエストを行ないます。
先に、neturl命令によりファイル名を除いたURLを指定しておく
必要があります。
netload命令は、ファイルの取得が終了するまで、処理を中断します。
手軽にファイルの取得を行なうことが可能ですが、大きなファイルや
受信状態の悪い場合などは、そのまま画面が停止したままになる
可能性もあるので注意してください。
ファイルの受信中に、並行して別な処理を行ないたい場合には、
netrequest命令を使用してhttpリクエストを行なってください。
netfileinfo p1,"FileName" httpファイル情報取得
p1 : ファイル情報が代入される変数名
"FileName" : リクエストを行なうファイル名
httpサーバー上にあるファイル情報を取得します。
先に、neturl命令によりファイル名を除いたURLを指定しておく
必要があります。
取得に成功すると、システム変数statの値が0となり、p1で指定した
変数に文字列型でサーバーが返した情報文字列が代入されます。
取得に失敗した場合は、システム変数statに0以外が代入されます。
サーバーが返す情報の種類は、httpサーバーによって異なります。
詳しくは、RFCなどhttpプロトコルの解説を参照してください。
netfileinfo命令は、ファイルの取得が終了するまで、処理を中断します。
netdlname "FileName" ダウンロード名の設定
"FileName" : ダウンロードされた時のファイル名
ファイルを取得する際のファイル名を設定します。
netdlname命令によってファイル名を設定していない場合は、
httpリクエストを行なったファイル名が使用されます。
netdlname命令に、空の文字列("")を指定した場合も、
httpリクエストを行なったファイル名が使用されます。
netproxy "ServerName",p1,p2 プロキシの設定
"ServerName" : リクエストを行なうファイル名
p1 (0) : ポート番号
p2 (0) : ローカル接続フラグ
http接続の際に使用されるプロキシ(代理)サーバーを設定します。
"ServerName"で、プロキシサーバー名を設定します。
空の文字列("")を指定した場合には、プロキシは設定されません。
p1でhttpが使用するプロキシサーバーのポート番号を指定します。
p2で、ローカルアドレスをプロキシ経由のアクセスから除外するか
どうかを設定します。1の場合は、ローカルアドレスのみプロキシから
除外されます。0の場合は、ローカルアドレスも含めてプロキシを
使用します。
netproxy命令が実行されると、それまでのセッションが解除され、
neturl命令や、netheader命令による設定はリセットされます。
例:
netinit
if stat : dialog "ネット接続できません。" : end
netproxy "proxy_server",8080,1
neturl "http://ww.onionsoft.net/hsp/"
netload "index.html"
netagent "AgentName" エージェントの設定
"AgentName" : 設定するエージェント名
http接続の際にサーバーに渡されるエージェント情報の文字列を
設定します。"AgentName"で指定したエージェント名が設定されます。
空の文字列("")を指定した場合には、デフォルトの設定になります。
netagent命令が実行されると、それまでのセッションが解除され、
neturl命令や、netheader命令による設定はリセットされます。
netheader "HeaderString" ヘッダ文字列の設定
"HeaderString" : ヘッダに追加される文字列
http接続の際にサーバーに渡されるヘッダ文字列を設定します。
空の文字列("")を指定した場合には、無設定になります。
ヘッダ文字列は、通常設定する必要ありませんが、何からの
付加情報や動作設定を行なう場合に使用することができます。
netheader命令で設定したヘッダ文字列は、それ以降のリクエスト
すべてに適用されます。
例:
; リファラーを追加する
netheader "Referer:http://www.onionsoft.net/\n\n"
netsize p1 ファイル受信サイズの取得
p1 : ファイル受信サイズが代入される変数
netrequest命令で発行されたhttpリクエストに対するファイル
がどれだけのサイズを受信したかを取得します。
p1で指定された変数にファイル受信サイズが代入されます。
ファイル受信サイズは、netexec命令で受信が行なわれた内容を
調べるためのものです。あらかじめ、ファイル情報取得で
ファイルサイズを調べておけば、進行の割合を計ることが可能です。
・ファイル関連命令
ローカルのファイルに対してアクセスするための命令セットです。
net〜関連命令とは関係なく使用することができます。
filecrc p1,"FileName" ファイルのCRC32を取得
p1 : CRC値が代入される変数名
"FileName" : CRCチェックを行なうファイル名
指定されたファイルのCRC32を求めてp1の変数に代入します。
CRC32は、ファイルの内容をもとに算出された32bitの数値です。
ファイル内容のチェックなどに使用することができます。
filemd5 p1,"FileName" ファイルのMD5を取得
p1 : MD5値が代入される変数名
"FileName" : MD5チェックを行なうファイル名
指定されたファイルのMD5を求めてp1の変数に代入します。
MD5値は、文字列型で「f96b697d7cb7938d525a2f31aaf161d0」のような
32文字の16進数として表現されます。
MD5値は、ファイルの内容を一意に表わすハッシュ値として使用する
ことができます。詳しくは、MD5についての資料などを参照してください。
ファイル内容のチェックなどに使用することができます。
ftpopen p1,p2,p3,p4 FTPセッションの開始
p1 : ftpサーバーアドレス(文字列)
p2 : ftpログインユーザー名(文字列)
p3 : ftpログインユーザーパスワード(文字列)
p4 : ポート番号(省略可能)
ftpサーバーに接続してセッションを開始します。
p1にサーバーのアドレス、p2にユーザー名、p3にパスワードを
指定してftpに接続します。
p4パラメーターでポート番号を指定することができます。
p4の指定を省略した場合は、標準のポート番号が使用されます。
実行に成功した場合は、システム変数statに0が代入され、
失敗した場合はそれ以外の値が代入されます。
あらかじめ、netinit命令によって初期化を行なう必要があります。
ftpセッションを開始した後は、ftp関連命令のみ使用することが
できます。httpなど他のネット操作を行なう場合には、必ず
ftpclose命令によりftpセッションを終了させるようにしてください。
ftpclose FTPセッションの終了
ftpopen命令で開始されたセッションを終了させます。
ftpresult p1 FTP処理結果文字列の取得
p1 : FTP処理結果文字列が代入される変数
ftp関連命令による処理に対するサーバーの返信メッセージを
取得して、p1に指定された変数に代入します。
p1の変数には、文字列データとして代入されます。
この命令は、必ずftpopen命令によりftpセッションを開始してから
使用してください。
ftpdir p1,p2 FTPディレクトリ移動
p1 : 現在のディレクトリ位置が代入される変数
p2 : 移動先のディレクトリ名(文字列)
p1で指定した変数に、ftpサーバー上のカレントディレクトリ名
を文字列データとして代入します。
p2にディレクトリ名を指定した場合には、その場所へ移動を行ないます。
p2の指定を省略した場合には、ディレクトリ移動は行なわれません。
実行に成功した場合は、システム変数statに0が代入され、
失敗した場合はそれ以外の値が代入されます。
この命令は、必ずftpopen命令によりftpセッションを開始してから
使用してください。
ftpdirlist FTPディレクトリリスト取得1
ftpサーバー上のカレントディレクトリにあるファイルリストを
取得するためのリクエストを行ないます。実際のファイルリストは、
ftpdirlist2命令で行ないます。
実行に成功した場合は、システム変数statに0が代入され、
失敗した場合はそれ以外の値が代入されます。
この命令は、必ずftpopen命令によりftpセッションを開始してから
使用してください。
ftpdirlist2 p1 FTPディレクトリリスト取得2
p1 : ファイルリストが代入される変数
この命令は、必ずftpopen命令によりftpセッションを開始し、
ftpdirlist命令によりファイルリスト取得が終了した後で使用して
ください。
以下は、ファイルリスト取得するまでの例です。
例:
; 結果待ちのためのループ
ftpdirlist
repeat
netexec mode
if res : break
await 50
loop
ftpdirlist2 res
ファイルリスト取得は、ftpdirlist命令によるリクエスト、
netexec命令による受信待ち、ftpdirlist2命令による結果の取得
という３つの手順に分けて行なう必要があります。
p1に代入されるファイルリストは、１行あたり１エントリごとに
区切られている複数行文字列データになります。
１行は、「"ファイル名"」、ファイルサイズ、更新日時の順番に
「,」で区切られた形になります。
ftpcmd p1 FTPコマンドの実行
p1 : 実行するFTPコマンド文字列
p1で指定されたFTPコマンドを実行します。
実行に成功した場合は、システム変数statに0が代入され、
失敗した場合はそれ以外の値が代入されます。
この命令は、必ずftpopen命令によりftpセッションを開始してから
使用してください。
ftprmdir p1 FTPディレクトリの削除
p1 : 削除するディレクトリを示す文字列
p1で指定されたディレクトリを削除します。
実行に成功した場合は、システム変数statに0が代入され、
失敗した場合はそれ以外の値が代入されます。
この命令は、必ずftpopen命令によりftpセッションを開始してから
使用してください。
ftpmkdir p1 FTPディレクトリの作成
p1 : 作成するディレクトリを示す文字列
p1で指定されたディレクトリを作成します。
実行に成功した場合は、システム変数statに0が代入され、
失敗した場合はそれ以外の値が代入されます。
この命令は、必ずftpopen命令によりftpセッションを開始してから
使用してください。
ftpget p1,p2,p3 FTPファイル取得
p1 : サーバー上から取得するファイル名(文字列)
p2("") : ローカルに作成されるファイル名(文字列)
p3(0) : 転送モード(0=バイナリ/1=アスキー)
ftpサーバー上のファイルを取得します。
p1でサーバー上のファイル名を指定します。
p2でダウンロードして作成されるファイル名を指定します。
p2の指定を省略または""にした場合は、p1と同じ名前が使用
されます。
p3で転送モードを指定します。転送モードを省略または0に
指定した場合はバイナリデータとして、1に指定した場合は、
アスキーデータとして転送を行ないます。
実行に成功した場合は、システム変数statに0が代入され、
失敗した場合はそれ以外の値が代入されます。
この命令は、必ずftpopen命令によりftpセッションを開始してから
使用してください。
ftpput p1,p2,p3 FTPファイル送信
p1 : サーバー上に作成するファイル名(文字列)
p2("") : ローカルから送信されるファイル名(文字列)
p3(0) : 転送モード(0=バイナリ/1=アスキー)
ftpサーバー上にファイルを送信します。
p1でサーバー上に作成するファイル名を指定します。
p2でローカルから送信されるファイル名を指定します。
p2の指定を省略または""にした場合は、p1と同じ名前が使用
されます。
p3で転送モードを指定します。転送モードを省略または0に
指定した場合はバイナリデータとして、1に指定した場合は、
アスキーデータとして転送を行ないます。
実行に成功した場合は、システム変数statに0が代入され、
失敗した場合はそれ以外の値が代入されます。
この命令は、必ずftpopen命令によりftpセッションを開始してから
使用してください。
ftprename p1,p2 FTPファイル名前変更
p1 : 変更元のファイル名(文字列)
p2 : 新しいファイル名(文字列)
ftpサーバー上のファイル名を変更します。
p1で変更元のファイル名を、p2で新しいファイル名を指定します。
実行に成功した場合は、システム変数statに0が代入され、
失敗した場合はそれ以外の値が代入されます。
この命令は、必ずftpopen命令によりftpセッションを開始してから
使用してください。
ftpdelete p1 FTPファイル削除
p1 : 削除するファイル名(文字列)
ftpサーバー上のファイルを削除します。
実行に成功した場合は、システム変数statに0が代入され、
失敗した場合はそれ以外の値が代入されます。
この命令は、必ずftpopen命令によりftpセッションを開始してから
使用してください。
-------------------------------------------------------------------------------
HSP users manual / end of file
-------------------------------------------------------------------------------