はじめに

このヘルプについて

 初期設定ファイルアクセスクラスをダウンロードしていただき、有り難うございます。
 このヘルプは、W3C HTML4.0で記述されていますので、これに対応したブラウザでご覧下さい。配色及びレイアウトにはCSSを利用しているので、CSS対応のブラウザでご覧になると表示がきれいになります。文字コードはシフトJISです。表示確認は Windows98 + NetscapeNavigator4.05 及び eOS R4 Intel + NetPositive で行っております。
 説明しなくても分かるような事柄は記述しないことがあります。あらかじめご了承下さい。

概要

 Windowsで使われる初期設定ファイル(INIファイル)と同形式のファイルにアクセスするためのクラスです。
 Windows版と互換性を保ちたいときや、ユーザーが設定をいじれるようにしたい場合などに使って下さい。

インストールとアンインストール

アーカイブの内容

 アーカイブには、以下のファイルが含まれています。


SHIFile.cpp       …… ファイルアクセスクラスソースファイル
SHIFile.h         ……           〃          ヘッダーファイル
SHIFile.htm       ……           〃          ヘルプファイル本体
iSHIFile.htm      ……           〃          ヘルプファイル目次
_SHIFile.htm      ……           〃          ヘルプファイル内容
IniFile.cpp       …… 初期設定ファイルアクセスクラスソースファイル
IniFile.h         ……               〃              ヘッダーファイル
IniFile.htm       ……               〃              ヘルプファイル本体
iIniFile.htm      ……               〃              ヘルプファイル目次
_IniFile.htm      ……               〃              ヘルプファイル内容
IniFileSample.cpp ……               〃              利用のサンプル
SHIHelp.css       …… ヘルプファイルスタイルシート
*.txt             …… テキスト文書

インストール

1.文字列操作関数を別途入手します。文字列操作関数は翔星ワールドにあります。
2.アーカイブ内及び文字列操作関数のソースファイルとヘッダーファイルを、インクルードパスの通ったフォルダまたはそのサブフォルダにコピーします。

アンインストール

 コピーしたファイルを全て削除します。

使い方

プロジェクトへの組み込み

1.IniFile.cpp、SHIFile.cpp、SHIString.cpp をプロジェクトに追加します。
2.関数を利用するソースファイルまたはそのヘッダーファイルで、IniFile.h をインクルードします。

大まかな流れ

 初期設定ファイルは複数のセクションから成り立っており、各セクションにはキーと値の組が複数記録されています。このため、まず ChangeSection() でアクセスするセクションを変更した後、ReadValue() や WriteValue() を用い、キーを指定してそのキーとペアになっている値を読み書きします。

具体例

 IniFileSample.cpp を参考にして下さい。

TIniFile リファレンス

TIniFile クラス

 TIniFile クラスは、アプリケーションの設定などを記録しておく初期設定ファイル(INIファイル)にアクセスするための機能を提供します。初期設定ファイルは、Windows上で使われる初期設定ファイルと同形式で、次のようになっています。

[ My Section #1 ]
; ここはコメント行
MyKey = Value
[ My Section #2 ]
RAM = 128
FDD = 1.44
PCName = PC98-NX

 [] で囲まれているのがセクション名です。上の例では、My Section #1 と、My Section #2 という2つのセクションが存在することになります。各セクションには、コメントや、キーと値のペアを複数記録することができます。セミコロンで始まる行がコメントです。それ以外の行では、イコールの左側がキー、右側が値です。My Section #1 には、キーが MyKey、値が Value というペアが存在します。同様に、My Section #2 にはペアが3つ存在しています。
 TIniFile クラスは、BFile > TSHIFile > TIniFile というように派生しているので、基本的な使い方は BFile クラスと同じです。ただし、効率化のため、ファイルへの物理的なアクセスには先読み・遅延書き込みを採用しているので、Read() や Write() を使うのはやめて下さい。代わりに ReadValue() や WriteValue() を使って下さい。
 以下では、TIniFile クラスで追加・更新された関数を紹介しています。

コンストラクタ

TIniFile(int iMaxLen = IniFileMaxLen);
TIniFile(const entry_ref *ref,uint32 open_mode,int iMaxLen = IniFileMaxLen);
TIniFile(const BEntry *entry,uint32 open_mode,int iMaxLen = IniFileMaxLen);
TIniFile(const char *path,uint32 open_mode,int iMaxLen = IniFileMaxLen);
TIniFile(const BDirectory *dir,const char *path,uint32 open_mode,int iMaxLen = IniFileMaxLen);
TIniFile(const BFile &file,int iMaxLen = IniFileMaxLen);

 BFile クラスのコンストラクタと似ていますが、引数が1つ増えています。iMaxLen は1行の最大の長さ[バイト]です。初期設定ファイルの1行はキーと値で構成されますので、これらが充分に入る長さを指定して下さい。デフォルトでは 2048 です。

ChangeSection()

virtual bool ChangeSection(const char *cSecName);

 値を読み書きするセクション(カレントセクション)を変更します。ReadValue()WriteValue() などを呼び出す前に、ChangeSection() で適切なセクションを指定して下さい。
 cSecName はセクションの名前です。セクション名に定数 GlobalSection を指定した場合や、1度も ChangeSection() していない間は、カレントセクションはグローバルセクション(どのセクションにも属さない、ファイルの先頭に記録されるセクション)になります。なお、指定したセクションがファイルに存在しない場合は新たに作成されます。
 返り値は、セクションの変更に成功すると true、失敗すると false です。でも失敗しないので常に true です(^^)。

 使用例:

ChangeSection("Display Color");
ChangeSection(GlobalSection);

DeleteKey()

virtual bool DeleteKey(const char *cKey);

 キー及びそれとペアになっている値を削除します。
 cKey は削除したいキーの名前です。
 返り値は、削除に成功した場合が true、失敗した場合が false です。

DeleteSection()

virtual bool DeleteSection(const char *cSecName);

 セクション及びそのセクションに属する全てのペア・コメントを削除します。
 cSecName は削除したいセクションの名前です。  返り値は、削除に成功した場合が true、失敗した場合が false です。

EnumKeys()

virtual void EnumKeys(BList *xList);

 カレントセクションに存在するキーを列挙します。
 xList には、列挙したキーの名前がアイテムとして格納されます。アイテム(キーの名前)の1つ1つは char* 型です。アイテムの内容を変更したり、アイテムが占有しているメモリを解放したりしないで下さい。
 返り値はありません。

 使用例:

char	cTmp[1001];
int		i;
BList	xList;
EnumKeys(&xList);
for ( i = 0 ; i < xList.CountItems() ; i++ )
	strcpy(cTmp,(char *)xList.ItemAt(i));

EnumSections()

virtual void EnumSections(BList *xList);

 セクションを列挙します。
 xList には、列挙したセクションの名前がアイテムとして格納されます。アイテム(セクションの名前)の1つ1つは char* 型です。アイテムの内容を変更したり、アイテムが占有しているメモリを解放したりしないで下さい。
 返り値はありません。

Flush()

virtual bool Flush(bool bForce = false);

 ファイルに実際に値を書き込みます。WriteValue() を呼び出しても値はメモリに書き込まれるだけで、物理的にファイルに書き込まれるわけではありません。普通、実際にファイルに書き込まれるのは TIniFile オブジェクトが破棄される直前などですが、Flush() を呼び出せば即座にファイルに書き込むことができます。
 bForce は、書き込みを強制するかどうかを指定します。bForce を false にすれば、前回 Flush() を呼び出してから1度も WriteValue() を呼び出していない場合など、実際にファイルに書き込む必要がない場合は書き込みがスキップされるので処理が高速になります。問答無用に書き込みたい場合は bForce を true にして下さい。
 返り値は、実際に書き込みを行った場合は true、書き込まなかった場合は false になります。

KeyExists()

virtual bool KeyExists(const char *cKey);

 キーが存在するか調べます。
 cKey は、調べたいキーの名前です。
 返り値は、キーが存在する場合が true、存在しない場合が false です。

ReadComment()

virtual bool ReadComment(char *cComment);

 初期設定ファイルの各セクションにはコメントが記入されている場合があります。ReadComment() はそのコメントを1行読み込みます。ReadComment() を繰り返し呼び出せば、何行でもコメントを読み込むことができます。
 cComment は読み込んだコメントを格納する配列へのポインタです。cComment は、読み込んだコメントを格納するのに充分な大きさを持っていなければなりません。具体的には、コンストラクタで指定した iMaxLen+1 あれば充分です。
 返り値は、コメントの読み出しに成功した場合が true、読めなかった場合が false です。

 使用例:

while ( ReadComment(cTmp) == true )
	puts(cTmp);

ReadValue()

virtual bool ReadValue(const char *cKey,char *cValue);
virtual bool ReadValue(const char *cKey,int32 *iValue);
virtual bool ReadValue(const char *cKey,int64 *iValue);
virtual bool ReadValue(const char *cKey,float *fValue);
virtual bool ReadValue(const char *cKey,rgb_color *iValue);

 カレントセクションから、キーとペアになっている値を読み込みます。
 cKey はキーの名前です。
 第2引数は読み込んだ値を格納する変数へのポインタです。値の読み込みに失敗した場合は変数の値は変更されません。
 返り値は、読み込みに成功した場合が true、カレントセクションに指定したキーが存在しないなどの理由で読み込みに失敗した場合は false になります。

 使用例:

ReadValue("RAM",&iRAMSize);
ReadValue("PCName",cPCName);

SectionExists()

virtual bool SectionExists(const char *cSecName);

 セクションが存在するか調べます。
 cKey は、調べたいセクションの名前です。
 返り値は、セクションが存在する場合が true、存在しない場合が false です。

SetTo()

virtual status_t SetTo(const entry_ref *ref,uint32 openMode,int iMaxLen = IniFileMaxLen);
virtual status_t SetTo(const BEntry *entry,uint32 openMode,int iMaxLen = IniFileMaxLen);
virtual status_t SetTo(const char *path,uint32 openMode,int iMaxLen = IniFileMaxLen);
virtual status_t SetTo(const BDirectory *dir,const char *path,uint32 openMode,int iMaxLen = IniFileMaxLen);

 BFile クラスの SetTo() と同様の働きをします。最後の引数 iMaxLen についてはコンストラクタを参照して下さい。

WriteComment()

virtual void WriteComment(const char *cComment);

 コメントを書き込みます。コメントはセクションの先頭に書き込まれます。
 cComment は書き込むコメントです。
 返り値はありません。

 使用例:

WriteComment("これは1行目のコメントです。");
WriteComment("2行目のコメントだよん。");

WriteValue()

virtual void WriteValue(const char *cKey,const char *cValue);
virtual void WriteValue(const char *cKey,int32 iValue);
virtual void WriteValue(const char *cKey,int64 iValue);
virtual void WriteValue(const char *cKey,float fValue);
virtual void WriteValue(const char *cKey,rgb_color xValue);

 キーと値のペアを書き込みます。
 cKey はキーの名前です。同名のキーが既に存在する場合、値は上書きされます。別々のセクションに同名のキーを存在させることは可能です。
 第2引数は値です。
 返り値はありません。

 使用例:

WriteValue("FDD",1.44);
WriteValue("PCName","PC98-NX");

困った時は

問題解決の手順

1.ヘルプをよく読みます。特に、Q&Aトラブルシューティングの所は念入りに読みます。そして、ヘルプに書かれていることを元にして問題を解決します。
2.SHINTAのホームページ『翔星ワールド』内の「サポートセンター」を訪れ、そこの情報を元にして問題を解決します。
3.翔星ワールド』内の「ソフトスタンド」から初期設定ファイルアクセスクラスの最新版をダウンロードし、最新版を使ってみます。
4.もしそれでも解決しなかったら、最終手段として、連絡先にメールを出します。その際は、初期設定ファイルアクセスクラスのバージョンと、問題の発生状況などを詳しく分かりやすく書いて下さい。そして、サポートセンターの情報の更新や、初期設定ファイルアクセスクラスのバージョンアップを待ちます。但し、連絡先などの所にも書いてあるとおり、回答には時間がかかることがあります。

Q&A

 現在の所、Q&Aに登録されている質問はありません。

トラブルシューティング

 現在の所、トラブルシューティングに登録されている事例はありません。

その他

著作権など

 このソフトウェア(初期設定ファイルアクセスクラス)はオープンウェアです。
 このソフトウェア(付属物を含む、以降同)の著作権は、第3者に提供された部分を除き、作者である私SHINTAに帰属します。これらは著作権法上の保護を受けています。
 私はバージョンアップ、サポート、バグ修正の義務を負わないこととします。
 このソフトウェアを使用したことによる結果及びその影響について、私はいかなる責任も負いません。全て各自の責任で使用して下さい。
 このソフトウェアは自由に改変して構いませんが、オリジナルの著作権表示は残して下さい。
 このソフトウェアの一部または全部を、SHINTAから承諾を得ずに販売等することを禁じます。
 その他、明記されていないことについてはSHINTAの意向が優先されます。
 このソフトウェアは以下のことを守って頂ければ自由に転載・配布して構いません。

・オリジナルを再配布する場合は、アーカイブの内容を変えないで下さい。解凍〜再圧縮したものも不可とします。改変した物の場合は、改変したことを明記して下さい。
・金銭その他の物品の授受を行わないで下さい。但し、ディスク代等の実費またはそれに相当する物品はこの限りではありません。
・非商用利用の場合は、事後で構いませんので私にご一報下さい。
・商用利用の場合は、商用利用についてに従って下さい。
・バージョンアップ等があった場合、転載者はなるべく最新版の再配布を行って下さい。

商用利用について

 このソフトウェアを商用で利用する時は、著作権などに記述されていることの他に、以下のことを守って下さい。
・商用BBSでの配布は、非商用利用と同等の扱いをします。
・雑誌や書籍、CD-ROM等に掲載・添付する場合は、掲載誌をお送り下さい。その場合、許可は不要です。その他に何か気持ち程度のもの(図書券でも菓子折りでも構いません)を頂けると幸いです。それ以外の場合は事前に私に許可を求めて下さい。なお、原稿が必要な場合はその旨を伝えて下さい。
・店頭デモは自由に行って構いません。許可は不要です。但し、このソフトウェアを添付しての販売は禁止します。
・その他の場合は、別途条件を考えますので事前に私にお問い合わせ下さい。

データベース

種 類 別オープンウェア
名  称ライブラリ
品  名初期設定ファイルアクセスクラス
バージョンVer 1.5
動作環境BeOS R4 for Intel
作  者SHINTA
作者Eメールk-shinta@mvb.biglobe.ne.jp
作者ホームページhttp://www.geocities.com/SiliconValley/Station/8180/Trans.htm (自動転送ページ)
http://www2u.biglobe.ne.jp/~shinta/ (メインページ)

動作確認環境

 初期設定ファイルアクセスクラスの動作確認は、以下の環境で行っております。

パソコン本体GP6-400 (Gateway)
C P UIntel PentiumII 400MHz
メ モ リ128MB
H D D10GB
CD-ROM最大32倍速
O  SBeOS R4 for Intel

改訂履歴

 SHIFile.cpp に書いてあります。

連絡先など

 このソフトウェアに関する情報や、このソフトウェアの最新版はSHINTAのホームページ『翔星ワールド』にあります。是非ご利用下さい。
 ご意見、ご感想(このソフトウェアの良い点や悪い点等)、ご要望、ご質問、アドバイス、バグレポート等がございましたら、メールを下さい。その際は、このソフトウェア及びOSの名前とバージョンを書いて下さるようお願いします。また、サポートできるのは最新版のみです(旧バージョンは最新版のコンパイル時に消えて無くなってしまうので)。但し旧バージョンでも、SHINTAの記憶に残っている部分や最新版と仕様が同じ部分についてはこの限りではありません。
 メールアドレスはk-shinta@mvb.biglobe.ne.jpです。いただいたご意見等は、なるべく今後の参考にしていきます。質問をいただいた場合には、次のいずれかの対応をしたいと考えています。

 ・翔星ワールド内のサポートセンターで回答を公開
 ・バージョンアップの時にヘルプ上で回答
 ・直接メールで回答

 メールがたくさん届いてしまった時などは、回答までに時間がかかるかもしれませんがご了承下さい。
 なお、メールを送る時は以下のことをお願いします。

・text/plain形式でお願いします。HTML形式等では読めません。
・いきなりバイナリを送るのはご遠慮下さい。前もってSHINTAに打診して下さるようお願いします。
・返信アドレスは正確にお願いします。返信できない時は困ってしまいます。