この章は libgnome のリファレンスとなるつもりである。
This chapter is intended to be a reference to the libgnome.
Miguel de Icaza <miguel@nuclecu.unam.mx>
コンフィグレーションの情報データベースを操作するルーチンのセット
A set of routines for manipulating the database of configuration information.
"config path" - コンフィギュレーションデータベースからどの項目を 引き出すか指定する文字列。例えば、"/myapp/display_toolbox" という config path は、'myapp' がそのツールボックスを表示するかどうかという 設定を引き出すのに使われうるだろう。
"config path" - a string that specifies which item to retrieve from the configuration database. For example, a config path of "/myapp/display_toolbox" could be used to retrieve the setting for whether 'myapp' should display its toolbox.
"default" - コンフィギュレーションの項目を引き出す時、 もしその項目が見つからない場合に使われる値を指定する。
"default" - when retrieving a config item, specifies the value to be used if the item is not found.
"private configuration data" - 普通、コンフィギュレーションの項目のデータは .ini 様のフォーマットで ~user/.gnome ディレクトリ以下のファイルに置かれる。 これらのファイルは世界中で読むことができる[テキスト]形式である。 セキュリティーやプライバシーと関係する項目は gnome-config ルーチンの "private" なバージョンを使って保管され引き出される。そしてこれらの項目の データは ~user/.gnome_private ディレクトリ以下のファイルに置かれる。 そのファイルはそのユーザーとシステム管理者以外はアクセス不可である。
"private configuration data" - Normally, config item data is located in files under the ~user/.gnome directory in a .ini-like format. These files are world-readable. Items that have security or privacy implications are stored and retrieved using the "private" versions of the gnome-config routines, and the data for these items is stored in files under the ~user/.gnome_private directory, which is not accessable by anyone except that user and the system administrator.
"translated" strings - GNOME が多言語をサポートするということは コンフィギュレーションの項目に対して複数の言語が対応してなければならない ということだ。gnome_config_*get_translated_string() と gnome_config_*set_translated_string() を使って、どの言語に文字列の項目を アクセスしにいくべきかを指定できる。
"translated" strings - GNOME's multilingual support means that multiple languages must be supported for configuration items. The gnome_config_*get_translated_string() and gnome_config_*set_translated_string() routines allow you to specify which language a string item should be accessed for.
"section" - コンフィギュレーションの項目や他の section のかたまり。
"section" - a group of config items and other config sections
type
gnome_config_get_typename(const char *path);コンフィギュレーションの項目を引き出すルーチン。'typename' では string, translated_string, int, bool, float, vector のどれかを指定する。 gnome_config_get_string(), gnome_config_get_translated_string(), and gnome_config_get_vector(), の場合は、返り値を確保するために使用された メモリーの所有権がアプリケーションに引き渡される [＊ 多分 g_alloc or malloc で確保したメモリへのポインタを返すんでしょう] 。アプリケーションが終了した時、 そのメモリは、適切のために g_free() か g_string_array_free() を使って 解放されるべきである。
Routine to retrieve a config item. 'typename' would be one of string, translated_string, int, bool, float, or vector. In the case of the gnome_config_get_string(), gnome_config_get_translated_string(), and gnome_config_get_vector(), ownership of the memory used by the returned value is given over to the application. When the application is done with it, it should be freed using g_free() or g_string_array_free() as appropriate.
これらの関数と、"private" や "with_default" とを組み合わせたバージョンが 存在する。例えば、gnome_config_get_string(), gnome_config_get_string_with_default(), gnome_config_private_get_string(), gnome_config_private_get_string_with_default() というルーチンが存在する。
Combinations of "private" and "with_default" versions of these routines exist. For example, there are gnome_config_get_string(), gnome_config_get_string_with_default() gnome_config_private_get_string(), and gnome_config_private_get_string_with_default() routines.
char *myitem;
gboolean is_default;
myitem =
gnome_config_get_string_with_default("/foo/blah=DefaultValue", &is_default); |
const char *path
アクセスされるコンフィギュレーション項目への config path。
The config path to the config item being accessed.
gboolean *def (gnome_config_get_*_with_default() routines only)
gboolean 型の変数のアドレス。関数の返り値がデフォルトの値か、 コンフィギュレーションデータベースの指定された 'path' から引き出されたかを格納するために使われる。
Address of a gboolean variable. Used to return an indication to the caller as to whether the return value is a default value or was retrieved from the config database for the specified 'path'.
void
gnome_config_set_typename(const char *path, type value);コンフィギュレーションデータベースの指定された config path に 指定された値を保管する。
Stores the specified value into the configuration database at the specified config path.
すべての標準ルーチンには "private" のバージョンもあることに注意しなさい。 例: gnome_config_set_string() と gnome_config_private_set_string()
Note that there are "private" variations on all the regular routines, e.g. gnome_config_set_string() and gnome_config_private_set_string().
char *values[] = {"A one", "a two", "a three"};
gnome_config_set_vector("/foo/bar/baz", 3, values); |
gboolean
gnome_config_has_section(const char *path);このルーチンは、もし指定されたセクションか項目が存在すれば TRUE を、 しなければ FALSE を返す。
This routine returns TRUE if the specified section/item exists, xor FALSE if it does not.
対応する gnome_config_private_has_section() も利用可能である。
A parallel gnome_config_private_has_section() routine also is available.
if(gnome_config_has_section("/foo/bar/baz")) {
g_print("You have saved preferences.\n");
} else {
g_print("You haven't saved preferences yet.\n");
} |
const char *path
調べたい項目またはセクションの config path.
Config path of the item/section of interest
void
*gnome_config_init_iterator(const char *path);このルーチンはあるコンフィギュレーションのセクションにある項目 すべてからなるループを作るために使われる。gnome_config_iterator_next() は次のアイテムに進むために使われる。
This routine is used to begin a loop over all the items in a config section. gnome_config_iterator_next() is used to advance to the next item.
gnome_config_private_init_iterator() という変形版も存在することに注意。
Note that a gnome_config_private_init_iterator() variant exists.
gnome_config_iterator_next() の使用例を見なさい。
See the gnome_config_iterator_next() usage example
const char *path
コンフィギュレーションのセクション (そのセクションの中の項目がリストされる)
Config section to list the items in.
void
*gnome_config_init_iterator_sections(const char *path);このルーチンはあるコンフィギュレーションのセクションにある項目 すべてからなるループを作るために使われる。gnome_config_iterator_next() は次の項目に進むために使われる。
This routine is used to begin a loop over all the items in a config section. gnome_config_iterator_next() is used to advance to the next item.
gnome_config_private_init_iterator_sections() という変形版もあることに注意。
Note that a gnome_config_private_init_iterator_sections() variant exists.
gnome_config_iterator_next() の使用例を見なさい。
See the gnome_config_iterator_next() usage example
const char *path
コンフィギュレーションのセクション (そのセクションの下位のセクションが リストされる)
Config section to list the sub-sections of.
void
*gnome_config_iterator_next(void *s, char **key, char **value);この関数は通常はコンフィギュレーションの項目/セクションイテレータの ループの更新としてはたらく。返り値は gnome_config_iterator_next() が必要としている void 型のポインタか、もしこれ以上入手可能なデータが イテレータになければ NULL である。
This function normally serves as the loop update for a config item or section iterator. The return value is an opaque pointer needed by gnome_config_iterator_next, or NULL if there are no more available data in the iterator.
char *section_name, *key, *value;
void *section_iter, *item_iter;
GString *tmpstr;
tmpstr = g_string_new(NULL);
for(section_iter = gnome_config_init_iterator_sections("/foo");
section_iter != NULL;
section_iter = gnome_config_iterator_next(section_iter, NULL, §ion_name)) {
g_string_sprintf(tmpstr, "/foo/%s", section_name);
for(item_iter = gnome_config_init_iterator(tmpstr->str);
item_iter;
item_iter = gnome_config_iterator_next(item_iter, &key, &value)) {
g_print("Got key %s -> value %s in section %s of /foo\n",
key, value, section_name);
g_free(key); g_free(value);
}
g_free(section_name);
}
g_string_free(tmpstr); |
void *s
gnome_config_*_init_iterator_*() か gnome_config_iterator_next() の返り値。
A value returned by either gnome_config_*_init_iterator_*() or gnome_config_iterator_next().
char **key
char* 型変数のアドレス。項目のイテレータに対しては、キーへの [キーを格納しているメモリへの] ポインタを返すために使われる。 セクションのイテレータに対しては、これは NULL であるべきだ。
The address of a char * variable. Used to return a pointer to the key for item iterators. For section iterators, this should be NULL.
char **value
char* 型変数のアドレス。項目のイテレータに対しては値へのポインタを、 セクションのイテレータに対してはセクションの名前へのポインタを返すために 使われる。
The address of a char * variable. Used to return a pointer to the value for item iterators, or to the section name for section iterators.
void gnome_config_drop_all(void);gnome_config ルーチンは処理を速くするためにコンフィギュレーションの エントリーをメモリ内にキャッシュする。gnome_config_drop_all() を呼ぶと、 そのキャッシュがクリアされる。
The gnome_config routines cache the configuration entries in memory to increase speed. Calling gnome_config_drop_all() causes the cache to be cleared.
void gnome_config_sync(void);前に述べたように、gnome_config ルーチンは処理を速くするために、 コンフィギュレーションのエントリーをキャッシュする。このルーチンは キャッシュをディスクにフラッシュする。あなたは通常は、 gnome_config_set_* の処理をたくさん行なった後でこれを使うであろう。
As previously stated, the gnome_config routines cache configuration entries in memory to increase speed. This routine flushes the cache to disk - you would ordinarily use it after a number of gnome_config_set_* operations.
void gnome_config_clean_file(const char *path);void gnome_config_private_clean_file(const char *path);void gnome_config_clean_section(const char *path);void gnome_config_private_clean_section(const char *path);void gnome_config_clean_key(const char *path);void gnome_config_private_clean_key(const char *path);このルーチンは指定されたもの(ファイルか、セクションか、キーのいずれか) に関係するコンフィギュレーションのエントリー全てを削除する。
These routines delete all the configuration entries associated with the specified entity (either a file, section, or key).
char *val1, *val2;
gnome_config_set_string("/foo/bar", "baz");
val1 = gnome_config_get_string("/foo/bar");
gnome_config_clean_section("/foo");
val2 = gnome_config_get_string("/foo/bar");
if(val1 && val2 && !strcmp(val1, val2)) {
g_error("The values match! gnome_config_clean_section is broken!");
} else {
g_message("gnome_config_clean_section worked.");
} |
const char *path
削除するコンフィギュレーションの項目への config path。
The config path to the config item which is to be removed.
char *gnome_config_get_real_path(const char *path);char *gnome_config_private_get_real_path(const char *path);時として、プログラマはコンフィギュレーション項目が保管されている ローカルのファイル名を得たいと思うかもしれない。これらの関数 (現在はマクロとして実装されている) は、config path が渡されると、 そのファイル名を返す。
Occasionally an application writer may want to get the local filename where a config item is stored. When passed a config path, these routines (currently implemented as macros) return that filename.
char *filename = gnome_config_get_real_path("/foo/bar");
FILE *filehandle = fopen(filename, "w");
/* do devious things with the file */ |
const char *path
アクセスされるコンフィギュレーション項目への config path。
The config path to the config item being accessed.