From aded4e75efc21319d5a777bf53bc087587f0740c Mon Sep 17 00:00:00 2001 From: Cyrille Bagard Date: Sat, 4 Jan 2020 11:15:57 +0100 Subject: Refreshed the Python documentation for the core features. --- plugins/dex/format.c | 2 +- plugins/elf/format.c | 2 +- plugins/pychrysalide/core/demanglers.c | 23 ++++++++----- plugins/pychrysalide/core/global.c | 62 ++++++++++++++++++++++++---------- plugins/pychrysalide/core/module.c | 11 +++++- plugins/pychrysalide/core/params.c | 17 ++++++---- plugins/pychrysalide/core/processors.c | 46 +++++++++++++++---------- plugins/pychrysalide/core/queue.c | 14 ++++---- src/core/demanglers.c | 2 +- src/core/demanglers.h | 2 +- 10 files changed, 120 insertions(+), 61 deletions(-) diff --git a/plugins/dex/format.c b/plugins/dex/format.c index 53cdc29..728ab8b 100644 --- a/plugins/dex/format.c +++ b/plugins/dex/format.c @@ -185,7 +185,7 @@ static void g_dex_format_init(GDexFormat *format) bin_format = G_BIN_FORMAT(format); - bin_format->demangler = get_compiler_demangler_for_type("dex"); + bin_format->demangler = get_compiler_demangler_for_key("dex"); assert(bin_format->demangler != NULL); } diff --git a/plugins/elf/format.c b/plugins/elf/format.c index 08472e4..f576397 100644 --- a/plugins/elf/format.c +++ b/plugins/elf/format.c @@ -189,7 +189,7 @@ static void g_elf_format_init(GElfFormat *format) bin_format = G_BIN_FORMAT(format); - bin_format->demangler = get_compiler_demangler_for_type("itanium"); + bin_format->demangler = get_compiler_demangler_for_key("itanium"); assert(bin_format->demangler != NULL); } diff --git a/plugins/pychrysalide/core/demanglers.c b/plugins/pychrysalide/core/demanglers.c index 216b7e1..a967491 100644 --- a/plugins/pychrysalide/core/demanglers.c +++ b/plugins/pychrysalide/core/demanglers.c @@ -37,7 +37,7 @@ /* Fournit le décodeur de désignations correspondant à un type. */ -static PyObject *py_demanglers_get_for_type(PyObject *, PyObject *); +static PyObject *py_demanglers_get_demangler_for_key(PyObject *, PyObject *); @@ -54,17 +54,27 @@ static PyObject *py_demanglers_get_for_type(PyObject *, PyObject *); * * ******************************************************************************/ -static PyObject *py_demanglers_get_for_type(PyObject *self, PyObject *args) +static PyObject *py_demanglers_get_demangler_for_key(PyObject *self, PyObject *args) { PyObject *result; /* Désignation à retourner */ const char *key; /* Nom court du format */ int ret; /* Bilan de lecture des args. */ GCompDemangler *demangler; /* Décodeur mis en place */ +#define DEMANGLERS_GET_DEMANGLER_FOR_KEY_METHOD PYTHON_METHOD_DEF \ +( \ + get_demangler_for_key, "key, /", \ + METH_VARARGS, py_demanglers, \ + "Create a new demangler for a given type of encoding, provided as" \ + " a key string.\n" \ + "\n" \ + "The return instance is a pychrysalide.mangling.CompDemangler subclass."\ +) + ret = PyArg_ParseTuple(args, "s", &key); if (!ret) return NULL; - demangler = get_compiler_demangler_for_type(key); + demangler = get_compiler_demangler_for_key(key); if (demangler != NULL) { @@ -103,13 +113,8 @@ bool populate_core_module_with_demanglers(void) PyObject *module; /* Module à recompléter */ static PyMethodDef py_demanglers_methods[] = { - - { "get_for_type", py_demanglers_get_for_type, - METH_VARARGS, - "get_for_type(key, /)\n--\n\nCreate a new demangler for a given type of encoding." - }, + DEMANGLERS_GET_DEMANGLER_FOR_KEY_METHOD, { NULL } - }; module = get_access_to_python_module("pychrysalide.core"); diff --git a/plugins/pychrysalide/core/global.c b/plugins/pychrysalide/core/global.c index 86133d2..ff892a8 100644 --- a/plugins/pychrysalide/core/global.c +++ b/plugins/pychrysalide/core/global.c @@ -107,6 +107,16 @@ static PyObject *py_global_get_content_explorer(PyObject *self, PyObject *args) PyObject *result; /* Instance Python à retourner */ GContentExplorer *explorer; /* Gestionnaire natif récupéré */ +#define GLOBAL_GET_CONTENT_EXPLORER_METHOD PYTHON_METHOD_DEF \ +( \ + get_content_explorer, "", \ + METH_NOARGS, py_global, \ + "Get the global exploration manager discovering contents." \ + "\n" \ + "The returned object is a pychrysalide.analysis.ContentExplorer" \ + " instance used as singleton." \ +) + explorer = get_current_content_explorer(); if (explorer != NULL) @@ -143,6 +153,17 @@ static PyObject *py_global_get_content_resolver(PyObject *self, PyObject *args) PyObject *result; /* Instance Python à retourner */ GContentResolver *resolver; /* Gestionnaire natif récupéré */ +#define GLOBAL_GET_CONTENT_RESOLVER_METHOD PYTHON_METHOD_DEF \ +( \ + get_content_resolver, "", \ + METH_NOARGS, py_global, \ + "Get the global resolution manager translating binary contents" \ + " into loaded contents." \ + "\n" \ + "The returned object is a pychrysalide.analysis.ContentResolver" \ + " instance used as singleton." \ +) + resolver = get_current_content_resolver(); if (resolver != NULL) @@ -179,6 +200,16 @@ static PyObject *py_global_get_current_project(PyObject *self, PyObject *args) PyObject *result; /* Instance Python à retourner */ GStudyProject *project; /* Projet courant récupéré */ +#define GLOBAL_GET_CURRENT_PROJECT_METHOD PYTHON_METHOD_DEF \ +( \ + get_current_project, "", \ + METH_NOARGS, py_global, \ + "Get the current global project." \ + "\n" \ + "The returned object is an instance of type" \ + " pychrysalide.analysis.StudyProject." \ +) + project = get_current_project(); if (project != NULL) @@ -215,6 +246,16 @@ static PyObject *py_global_set_current_project(PyObject *self, PyObject *args) GStudyProject *project; /* Version GLib du projet */ int ret; /* Bilan de lecture des args. */ +#define GLOBAL_SET_CURRENT_PROJECT_METHOD PYTHON_METHOD_DEF \ +( \ + set_current_project, "project", \ + METH_VARARGS, py_global, \ + "Set the current global project." \ + "\n" \ + "The provided project has to be an instance (or a subclass)" \ + " of pychrysalide.analysis.StudyProject." \ +) + ret = PyArg_ParseTuple(args, "O&", convert_to_study_project, &project); if (!ret) return NULL; @@ -246,24 +287,11 @@ bool populate_core_module_with_global(void) static PyMethodDef py_global_methods[] = { GLOBAL_IS_BATCH_MODE_METHOD, - { "get_content_explorer", py_global_get_content_explorer, - METH_NOARGS, - "get_content_explorer(, /)\n--\n\nGet the global exploration manager discovering contents." - }, - { "get_content_resolver", py_global_get_content_resolver, - METH_NOARGS, - "get_content_resolver(, /)\n--\n\nGet the global resolution manager translating binary contents into loaded contents." - }, - { "get_current_project", py_global_get_current_project, - METH_NOARGS, - "get_current_project(, /)\n--\n\nGet the current global project." - }, - { "set_current_project", py_global_set_current_project, - METH_VARARGS, - "set_current_project(, /)\n--\n\nSet the current global project." - }, + GLOBAL_GET_CONTENT_EXPLORER_METHOD, + GLOBAL_GET_CONTENT_RESOLVER_METHOD, + GLOBAL_GET_CURRENT_PROJECT_METHOD, + GLOBAL_SET_CURRENT_PROJECT_METHOD, { NULL } - }; module = get_access_to_python_module("pychrysalide.core"); diff --git a/plugins/pychrysalide/core/module.c b/plugins/pychrysalide/core/module.c index d954821..27113a0 100644 --- a/plugins/pychrysalide/core/module.c +++ b/plugins/pychrysalide/core/module.c @@ -55,12 +55,21 @@ bool add_core_module(PyObject *super) bool result; /* Bilan à retourner */ PyObject *module; /* Sous-module mis en place */ +#define PYCHRYSALIDE_CORE_DOC \ + "This module provides access to the Chrysalide core properties through" \ + " the Python bindings.\n" \ + "\n" \ + "Most of these features are singleton objects.\n" \ + "\n" \ + "As attributes are not allowed for Python modules, all these" \ + " property accesses are handled with methods." + static PyModuleDef py_chrysalide_core_module = { .m_base = PyModuleDef_HEAD_INIT, .m_name = "pychrysalide.core", - .m_doc = "Python module for Chrysalide.core", + .m_doc = PYCHRYSALIDE_CORE_DOC, .m_size = -1, diff --git a/plugins/pychrysalide/core/params.c b/plugins/pychrysalide/core/params.c index b9d8741..0f23981 100644 --- a/plugins/pychrysalide/core/params.c +++ b/plugins/pychrysalide/core/params.c @@ -62,6 +62,16 @@ static PyObject *py_params_get_main_configuration(PyObject *self, PyObject *args PyObject *result; /* Instance GLib à retourner */ GGenConfig *config; /* Configuration à convertir */ +#define PARAMS_GET_MAIN_CONFIGURATION_METHOD PYTHON_METHOD_DEF \ +( \ + get_main_configuration, "", \ + METH_NOARGS, py_params, \ + "Give access to the main configuration of Chrysalide." \ + "\n" \ + "The returned object is an instance of type" \ + " pychrysalide.glibext.GenConfig." \ +) + config = get_main_configuration(); result = pygobject_new(G_OBJECT(config)); @@ -120,13 +130,8 @@ bool populate_core_module_with_params(void) PyObject *dict; /* Dictionnaire dudit module */ static PyMethodDef py_params_methods[] = { - - { "get_main_configuration", py_params_get_main_configuration, - METH_NOARGS, - "get_main_configuration(, /)\n--\n\nGive access to the main configuration of Chrysalide." - }, + PARAMS_GET_MAIN_CONFIGURATION_METHOD, { NULL } - }; module = get_access_to_python_module("pychrysalide.core"); diff --git a/plugins/pychrysalide/core/processors.c b/plugins/pychrysalide/core/processors.c index 47e4643..bd4a50f 100644 --- a/plugins/pychrysalide/core/processors.c +++ b/plugins/pychrysalide/core/processors.c @@ -41,10 +41,10 @@ /* Enregistre un processeur pour une architecture donnée. */ -static PyObject *py_processors_register_type(PyObject *, PyObject *); +static PyObject *py_processors_register_processor(PyObject *, PyObject *); /* Fournit le processeur d'architecture correspondant à un nom. */ -static PyObject *py_processors_get_for_key(PyObject *, PyObject *); +static PyObject *py_processors_get_processor_for_key(PyObject *, PyObject *); @@ -61,7 +61,7 @@ static PyObject *py_processors_get_for_key(PyObject *, PyObject *); * * ******************************************************************************/ -static PyObject *py_processors_register_type(PyObject *self, PyObject *args) +static PyObject *py_processors_register_processor(PyObject *self, PyObject *args) { PyObject *result; /* Bilan à retourner */ PyObject *type; /* Type d'une instance future */ @@ -72,6 +72,15 @@ static PyObject *py_processors_register_type(PyObject *self, PyObject *args) GType instance; /* Type pour futures instances */ bool status; /* Bilan d'un enregistrement */ +#define PROCESSORS_REGISTER_PROCESSOR_METHOD PYTHON_METHOD_DEF \ +( \ + register_processor, "inst, /", \ + METH_VARARGS, py_processors, \ + "Register an architecture processor using an initial instance of it.\n" \ + "\n" \ + "This instance has to be a subclass of pychrysalide.arch.ArchProcessor."\ +) + ret = PyArg_ParseTuple(args, "O!", &PyType_Type, &type); if (!ret) return NULL; @@ -130,17 +139,27 @@ static PyObject *py_processors_register_type(PyObject *self, PyObject *args) * * ******************************************************************************/ -static PyObject *py_processors_get_for_key(PyObject *self, PyObject *args) +static PyObject *py_processors_get_processor_for_key(PyObject *self, PyObject *args) { PyObject *result; /* Bilan à retourner */ - const char *name; /* Nom technique de processeur */ + const char *key; /* Nom technique de processeur */ int ret; /* Bilan de lecture des args. */ GArchProcessor *proc; /* Instance mise en place */ - ret = PyArg_ParseTuple(args, "s", &name); +#define PROCESSORS_GET_PROCESSOR_FOR_KEY_METHOD PYTHON_METHOD_DEF \ +( \ + get_processor_for_key, "key, /", \ + METH_VARARGS, py_processors, \ + "Provide an instance of an architecture processor for a given name," \ + " provided as a key string.\n" \ + "\n" \ + "The return instance is a pychrysalide.arch.ArchProcessor subclass." \ +) + + ret = PyArg_ParseTuple(args, "s", &key); if (!ret) return NULL; - proc = get_arch_processor_for_key(name); + proc = get_arch_processor_for_key(key); if (proc != NULL) { @@ -176,18 +195,9 @@ bool populate_core_module_with_processors(void) PyObject *module; /* Module à recompléter */ static PyMethodDef py_processors_methods[] = { - { - "register_processor", py_processors_register_type, - METH_VARARGS, - "register_processor(name, desc, cls, /)\n--\n\nRegister an an architecture processor by its name, description and class type." - }, - { - "get_processor_for_key", py_processors_get_for_key, - METH_VARARGS, - "get_processor_for_key(name, /)\n--\n\nProvide an instance of an architecture processor for a given name." - }, + PROCESSORS_REGISTER_PROCESSOR_METHOD, + PROCESSORS_GET_PROCESSOR_FOR_KEY_METHOD, { NULL } - }; module = get_access_to_python_module("pychrysalide.core"); diff --git a/plugins/pychrysalide/core/queue.c b/plugins/pychrysalide/core/queue.c index 8917712..cc76b77 100644 --- a/plugins/pychrysalide/core/queue.c +++ b/plugins/pychrysalide/core/queue.c @@ -58,6 +58,13 @@ static PyObject *py_queue_wait_for_all_global_works(PyObject *self, PyObject *ar { PyThreadState *_save; /* Sauvegarde de contexte */ +#define QUEUE_WAIT_FOR_ALL_GLOBAL_WORKS_METHOD PYTHON_METHOD_DEF \ +( \ + wait_for_all_global_works, "", \ + METH_NOARGS, py_queue, \ + "Wait for all global tasks being processed." \ +) + Py_UNBLOCK_THREADS; wait_for_all_global_works(); @@ -87,13 +94,8 @@ bool populate_core_module_with_queue(void) PyObject *module; /* Module à recompléter */ static PyMethodDef py_queue_methods[] = { - - { "wait_for_all_global_works", py_queue_wait_for_all_global_works, - METH_NOARGS, - "wait_for_all_global_works(, /)\n--\n\nWait for all tasks being processed." - }, + QUEUE_WAIT_FOR_ALL_GLOBAL_WORKS_METHOD, { NULL } - }; module = get_access_to_python_module("pychrysalide.core"); diff --git a/src/core/demanglers.c b/src/core/demanglers.c index 4b43f55..8d36e3f 100644 --- a/src/core/demanglers.c +++ b/src/core/demanglers.c @@ -170,7 +170,7 @@ static demangler_t *find_demangler_by_key(const char *key) * * ******************************************************************************/ -GCompDemangler *get_compiler_demangler_for_type(const char *key) +GCompDemangler *get_compiler_demangler_for_key(const char *key) { GCompDemangler *result; /* Instance à retourner */ demangler_t *def; /* Définition de décodeur */ diff --git a/src/core/demanglers.h b/src/core/demanglers.h index 35bdb49..6fa9fdb 100644 --- a/src/core/demanglers.h +++ b/src/core/demanglers.h @@ -39,7 +39,7 @@ bool register_demangler_type(const char *, GType); void unload_demanglers_definitions(void); /* Fournit le décodeur de désignations correspondant à un type. */ -GCompDemangler *get_compiler_demangler_for_type(const char *); +GCompDemangler *get_compiler_demangler_for_key(const char *); -- cgit v0.11.2-87-g4458