From 86895e88a955eb3a13f6bc2580697030aa7488e8 Mon Sep 17 00:00:00 2001 From: Marc-André Lureau Date: Mon, 17 Dec 2012 16:48:01 +0100 Subject: Add documentation and annotations --- libmsi/libmsi-database.c | 82 +++++++++++++++++++++++++++++++++++-- libmsi/libmsi-query.c | 62 +++++++++++++++++++++++++++- libmsi/libmsi-record.c | 6 +-- libmsi/libmsi-summary-info.c | 96 ++++++++++++++++++++++++++++++++++++++++++-- 4 files changed, 235 insertions(+), 11 deletions(-) (limited to 'libmsi') diff --git a/libmsi/libmsi-database.c b/libmsi/libmsi-database.c index 8120b4d..66fa04d 100644 --- a/libmsi/libmsi-database.c +++ b/libmsi/libmsi-database.c @@ -1186,6 +1186,16 @@ done: return r; } +/** + * libmsi_database_import: + * @db: a %LibmsiDatabase + * @path: path to a table file + * @error: (allow-none): #GError to set on error, or %NULL + * + * Import a table to the database from file @path. + * + * Returns: %TRUE on success + **/ gboolean libmsi_database_import (LibmsiDatabase *db, const char *path, @@ -1312,11 +1322,14 @@ done: return r; } -/*********************************************************************** - * MsiExportDatabase [MSI.@] +/** + * libmsi_database_export: + * @db: a %LibmsiDatabase + * @table: a table name + * @fd: a file descriptor + * @error: (allow-none): #GError to set on error, or %NULL * * Writes a file containing the table data as tab separated ASCII. - * * The format is as follows: * * row1 : colname1 colname2 .... colnameN @@ -1326,7 +1339,9 @@ done: * Followed by the data, starting at row 1 with one row per line * * row4 : data data data ... data - */ + * + * Returns: %TRUE on success + **/ gboolean libmsi_database_export (LibmsiDatabase *db, const char *table, @@ -1960,6 +1975,15 @@ static unsigned update_merge_errors(LibmsiDatabase *db, const char *error, return r; } +/** + * libmsi_database_merge: + * @db: a %LibmsiDatabase to merge into + * @merge: a %LibmsiDatabase to merge + * @table: (allow-none): an optionnal table name + * @error: (allow-none): #GError to set on error, or %NULL + * + * Returns: %TRUE on success + **/ gboolean libmsi_database_merge (LibmsiDatabase *db, LibmsiDatabase *merge, @@ -2023,6 +2047,12 @@ done: return r == LIBMSI_RESULT_SUCCESS; } +/** + * libmsi_database_is_readonly: + * @db: a %LibmsiDatabase + * + * Returns: %TRUE if the database is read-only. + **/ gboolean libmsi_database_is_readonly (LibmsiDatabase *db) { @@ -2175,6 +2205,16 @@ end: return ret; } +/** + * libmsi_database_apply_transform: + * @db: a %LibmsiDatabase + * @file: an MST transform file path + * @error: (allow-none): #GError to set on error, or %NULL + * + * FIXME + * + * Returns: %TRUE on success + **/ gboolean libmsi_database_apply_transform (LibmsiDatabase *db, const char *szTransformFile, @@ -2270,6 +2310,13 @@ end: return ret; } +/** + * libmsi_database_commit: + * @db: a #LibmsiDatabase + * @error: (allow-none): #GError to set on error, or %NULL + * + * Returns: %TRUE on success. + **/ gboolean libmsi_database_commit (LibmsiDatabase *db, GError **error) { @@ -2399,6 +2446,15 @@ unsigned _libmsi_database_get_primary_keys( LibmsiDatabase *db, return r; } +/** + * libmsi_database_get_primary_keys: + * @db: a %LibmsiDatabase + * @table: an exisiting table name + * @error: (allow-none): #GError to set on error, or %NULL + * + * Returns: (transfer full): a %LibmsiRecord containing the names of all the primary + * key columns. + **/ LibmsiRecord * libmsi_database_get_primary_keys (LibmsiDatabase *db, const char *table, @@ -2422,6 +2478,14 @@ libmsi_database_get_primary_keys (LibmsiDatabase *db, return rec; } +/** + * libmsi_database_is_table_persistent: + * @db: a %LibmsiDatabase + * @table: an exisiting table name + * @error: (allow-none): #GError to set on error, or %NULL + * + * Returns: %TRUE if the @table is persistent, %FALSE if it's temporary + **/ gboolean libmsi_database_is_table_persistent (LibmsiDatabase *db, const char *table, GError **error) @@ -2471,6 +2535,16 @@ init (LibmsiDatabase *self, GError **error) return !ret; } +/** + * libmsi_database_new: + * @path: path to a MSI file + * @persist: path to a MSI file or LIBMSI_DB_OPEN flag + * @error: (allow-none): #GError to set on error, or %NULL + * + * Create a MSI database or open from @path. + * + * Returns: a new #LibmsiDatabase on success, %NULL if fail. + **/ LibmsiDatabase * libmsi_database_new (const gchar *path, const char *persist, GError **error) { diff --git a/libmsi/libmsi-query.c b/libmsi/libmsi-query.c index 4952d32..1a951c9 100644 --- a/libmsi/libmsi-query.c +++ b/libmsi/libmsi-query.c @@ -396,6 +396,17 @@ LibmsiResult _libmsi_query_fetch(LibmsiQuery *query, LibmsiRecord **prec) return r; } +/** + * libmsi_query_fetch: + * @query: a #LibmsiQuery + * @error: (allow-none): return location for the error + * + * Return the next query result. A %LIBMSI_RESULT_NO_MORE_ITEMS error + * is returned when the query result set has reached the end. + * + * Returns: (transfer full): a newly allocated #LibmsiRecord + * or %NULL when no results or failure. + **/ LibmsiRecord * libmsi_query_fetch (LibmsiQuery *query, GError **error) { @@ -417,6 +428,15 @@ libmsi_query_fetch (LibmsiQuery *query, GError **error) return record; } +/** + * libmsi_query_close: + * @query: a #LibmsiQuery + * @error: (allow-none): return location for the error + * + * Release the current result set. + * + * Returns: %TRUE on success + **/ gboolean libmsi_query_close (LibmsiQuery *query, GError **error) { @@ -461,6 +481,17 @@ LibmsiResult _libmsi_query_execute(LibmsiQuery *query, LibmsiRecord *rec ) return view->ops->execute( view, rec ); } +/** + * libmsi_query_execute: + * @query: a #LibmsiQuery + * @rec: (allow-none): a #LibmsiRecord containing query arguments, or + * %NULL if no arguments needed + * @error: (allow-none): return location for the error + * + * Execute the @query with the arguments from @rec. + * + * Returns: %TRUE on success + **/ gboolean libmsi_query_execute (LibmsiQuery *query, LibmsiRecord *rec, GError **error) { @@ -564,6 +595,17 @@ LibmsiResult _libmsi_query_get_column_info( LibmsiQuery *query, LibmsiColInfo in return LIBMSI_RESULT_SUCCESS; } +/** + * libmsi_query_get_column_info: + * @query: a #LibmsiQuery + * @info: a #LibmsiColInfo specifying the type of information to return + * @error: (allow-none): return location for the error + * + * Get column informations, returned as record string fields. + * + * Returns: (transfer full): a newly allocated #LibmsiRecord + * containing informations or %NULL on error. + **/ LibmsiRecord * libmsi_query_get_column_info (LibmsiQuery *query, LibmsiColInfo info, GError **error) { @@ -588,6 +630,14 @@ libmsi_query_get_column_info (LibmsiQuery *query, LibmsiColInfo info, GError **e return rec; } +/** + * libmsi_query_get_error: + * @query: a #LibmsiQuery + * @column: (out) (allow-none): location to store the allocated column name + * @error: (allow-none): return location for the error + * + * Call this to get more information on the last query error. + **/ void libmsi_query_get_error (LibmsiQuery *query, gchar **column, GError **error) { @@ -605,7 +655,17 @@ libmsi_query_get_error (LibmsiQuery *query, gchar **column, GError **error) } } -LibmsiQuery* +/** + * libmsi_query_new: + * @database: a #LibmsiDatabase + * @query: a SQL query + * @error: (allow-none): #GError to set on error, or %NULL + * + * Create a SQL query for @database. + * + * Returns: a new %LibmsiQuery on success, %NULL on failure + **/ +LibmsiQuery * libmsi_query_new (LibmsiDatabase *database, const char *query, GError **error) { LibmsiQuery *self; diff --git a/libmsi/libmsi-record.c b/libmsi/libmsi-record.c index d451f20..aa77ad6 100644 --- a/libmsi/libmsi-record.c +++ b/libmsi/libmsi-record.c @@ -553,11 +553,11 @@ unsigned _libmsi_record_load_stream_from_file(LibmsiRecord *rec, unsigned field, /** * libmsi_record_load_stream: - * @record: a %LibmsiRecord + * @record: a #LibmsiRecord * @field: a field identifier * @filename: a filename or %NULL * - * Load the file content as a stream in %field. + * Load the file content as a stream in @field. * * Returns: %TRUE on success. **/ @@ -628,7 +628,7 @@ unsigned _libmsi_record_save_stream(const LibmsiRecord *rec, unsigned field, cha /** * libmsi_record_save_stream: - * @record: a %LibmsiRecord + * @rec: a %LibmsiRecord * @field: a field identifier * @buf: a buffer of size specified by %sz, or %NULL to return size * @sz: a pointer to %buf size diff --git a/libmsi/libmsi-summary-info.c b/libmsi/libmsi-summary-info.c index a185055..01410a0 100644 --- a/libmsi/libmsi-summary-info.c +++ b/libmsi/libmsi-summary-info.c @@ -194,6 +194,12 @@ static unsigned get_property_count( const LibmsiOLEVariant *property ) return n; } +/** + * libmsi_summary_info_get_properties: + * @si: a #LibmsiSummaryInfo + * + * Returns: (array) (element-type LibmsiProperty) (transfer full): a new #GArray with the list of set properties + **/ GArray * libmsi_summary_info_get_properties (LibmsiSummaryInfo *self) { @@ -557,6 +563,14 @@ static unsigned suminfo_persist( LibmsiSummaryInfo *si ) return r; } +/** + * libmsi_summary_info_get_property_type: + * @si: a #LibmsiSummaryInfo + * @prop: a #LibmsiProperty to get + * @error: (allow-none): #GError to set on error, or %NULL + * + * Returns: the property type associated for @prop. + **/ LibmsiPropertyType libmsi_summary_info_get_property_type (LibmsiSummaryInfo *self, LibmsiProperty prop, @@ -649,6 +663,14 @@ static void _summary_info_get_property (LibmsiSummaryInfo *si, unsigned uiProper g_object_unref (si); } +/** + * libmsi_summary_info_get_int: + * @si: a #LibmsiSummaryInfo + * @prop: a #LibmsiProperty to get + * @error: (allow-none): #GError to set on error, or %NULL + * + * Returns: the property value or -1 on failure + **/ gint libmsi_summary_info_get_int (LibmsiSummaryInfo *self, LibmsiProperty prop, GError **error) @@ -666,6 +688,14 @@ libmsi_summary_info_get_int (LibmsiSummaryInfo *self, LibmsiProperty prop, return val; } +/** + * libmsi_summary_info_get_filetime: + * @si: a #LibmsiSummaryInfo + * @prop: a #LibmsiProperty to get + * @error: (allow-none): #GError to set on error, or %NULL + * + * Returns: the property value or 0 on failure + **/ guint64 libmsi_summary_info_get_filetime (LibmsiSummaryInfo *self, LibmsiProperty prop, GError **error) @@ -683,6 +713,14 @@ libmsi_summary_info_get_filetime (LibmsiSummaryInfo *self, LibmsiProperty prop, return val; } +/** + * libmsi_summary_info_get_string: + * @si: a #LibmsiSummaryInfo + * @prop: a #LibmsiProperty to get + * @error: (allow-none): #GError to set on error, or %NULL + * + * Returns: the property value or %NULL on failure + **/ const gchar * libmsi_summary_info_get_string (LibmsiSummaryInfo *self, LibmsiProperty prop, GError **error) @@ -755,6 +793,17 @@ end: return ret; } +/** + * libmsi_summary_info_set_string: + * @si: a #LibmsiSummaryInfo + * @prop: a #LibmsiProperty to set + * @value: a string value + * @error: (allow-none): #GError to set on error, or %NULL + * + * Set string property @prop. + * + * Returns: %TRUE on success + **/ gboolean libmsi_summary_info_set_string (LibmsiSummaryInfo *self, LibmsiProperty prop, const gchar *value, GError **error) @@ -778,6 +827,17 @@ libmsi_summary_info_set_string (LibmsiSummaryInfo *self, LibmsiProperty prop, return TRUE; } +/** + * libmsi_summary_info_set_int: + * @si: a #LibmsiSummaryInfo + * @prop: a #LibmsiProperty to set + * @value: a value + * @error: (allow-none): #GError to set on error, or %NULL + * + * Set integer property @prop. + * + * Returns: %TRUE on success + **/ gboolean libmsi_summary_info_set_int (LibmsiSummaryInfo *self, LibmsiProperty prop, gint value, GError **error) @@ -803,6 +863,17 @@ libmsi_summary_info_set_int (LibmsiSummaryInfo *self, LibmsiProperty prop, return TRUE; } +/** + * libmsi_summary_info_set_filetime: + * @si: a #LibmsiSummaryInfo + * @prop: a #LibmsiProperty to set + * @value: a value + * @error: (allow-none): #GError to set on error, or %NULL + * + * Set file time property @prop. + * + * Returns: %TRUE on success + **/ gboolean libmsi_summary_info_set_filetime (LibmsiSummaryInfo *self, LibmsiProperty prop, guint64 value, GError **error) @@ -911,7 +982,17 @@ end: return r; } -gboolean libmsi_summary_info_persist (LibmsiSummaryInfo *si, GError **error) +/** + * libmsi_summary_info_persist: + * @si: a #LibmsiSummaryInfo + * @error: (allow-none): #GError to set on error, or %NULL + * + * Save summary informations. + * + * Returns: %TRUE on success + **/ +gboolean +libmsi_summary_info_persist (LibmsiSummaryInfo *si, GError **error) { unsigned ret; @@ -932,8 +1013,17 @@ gboolean libmsi_summary_info_persist (LibmsiSummaryInfo *si, GError **error) return ret == LIBMSI_RESULT_SUCCESS; } -LibmsiSummaryInfo* -libmsi_summary_info_new (LibmsiDatabase *database, unsigned update_count, GError **error) +/** + * libmsi_summary_info_new: + * @database: a #LibmsiDatabase + * @update_count: number of changes allowed + * @error: (allow-none): #GError to set on error, or %NULL + * + * Returns: a #LibmsiSummaryInfo or %NULL on failure + **/ +LibmsiSummaryInfo * +libmsi_summary_info_new (LibmsiDatabase *database, unsigned update_count, + GError **error) { LibmsiSummaryInfo *self; -- cgit