diff options
Diffstat (limited to 'include/asterisk/sorcery.h')
-rw-r--r-- | include/asterisk/sorcery.h | 24 |
1 files changed, 24 insertions, 0 deletions
diff --git a/include/asterisk/sorcery.h b/include/asterisk/sorcery.h index 027ec0058..5e947257b 100644 --- a/include/asterisk/sorcery.h +++ b/include/asterisk/sorcery.h @@ -1148,6 +1148,7 @@ void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char * /*! * \brief Retrieve an object or multiple objects using specific fields + * \since 13.9.0 * * \param sorcery Pointer to a sorcery structure * \param type Type of object to retrieve @@ -1162,6 +1163,29 @@ void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char * * * \note If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects * of the given type. + * + * \note The fields parameter can contain realtime-style expressions in variable->name. + * All operators defined for ast_strings_match can be used except for regex as + * there's no common support for regex in the realtime backends at this time. + * If multiple variables are in the fields list, all must match for an object to + * be returned. See ast_strings_match for more information. + * + * Example: + * + * The following code can be significantly faster when a realtime backend is in use + * because the expression "qualify_frequency > 0" is passed to the database to limit + * the number of rows returned. + * + * struct ast_variable *var = ast_variable_new("qualify_frequency >", "0", ""); + * struct ao2_container *aors; + * + * if (!var) { + * return; + * } + * + * aors = ast_sorcery_retrieve_by_fields(ast_sip_get_sorcery(), + * "aor", AST_RETRIEVE_FLAG_MULTIPLE, var); + * */ void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields); |