FFMPEG源码分析之 av_opt_set_dict()

1 av_opt_set_dict()

---

av_opt_set_dict() 声明：

• 所属库：libavutil（lavu）
• 头文件：libavutil/opt.h
• 声明：
  功能：设置所有的选项到一个对象中
  入参obj：将被应用选项的对象，该对象必须第一个成员为AVClass*，也即obj应该是某个上下文结构体对象
  入参options：需要被应用的选项字典。输入的选项字典将被释放，并且会被一个新的字典替代，这个新的字典中的选项由没有在obj中找到的所有选项组成。这个新的选项需要本函数的调用着在函数外部使用av_dict_free()来释放空间。
  返回值：成功返回0，当某些选项在obj中被找到，但是又设置失败，那么该函数返回负的错误码。

/**
 * Set all the options from a given dictionary on an object.
 *
 * @param obj a struct whose first element is a pointer to AVClass
 * @param options options to process. This dictionary will be freed and replaced
 *                by a new one containing all options not found in obj.
 *                Of course this new dictionary needs to be freed by caller
 *                with av_dict_free().
 *
 * @return 0 on success, a negative AVERROR if some option was found in obj,
 *         but could not be set.
 *
 * @see av_dict_copy()
 */
int av_opt_set_dict(void *obj, struct AVDictionary **options);

av_opt_set_dict() 源码：

• 所属库：libavutil（lavu）
• 源文件：libavutil/opt.c
• 源码：该函数简单的调用了av_opt_set_dict2()

  int av_opt_set_dict(void *obj, AVDictionary **options)
  {
      return av_opt_set_dict2(obj, options, 0);
  }

2 av_opt_set_dict2()

---

av_opt_set_dict() 声明：

• 所属库：libavutil（lavu）
• 头文件：libavutil/opt.h
• 声明：
  功能：这个函数与av_opt_set_dict()作用相同。但是多了一个参数search_flags。
  参数search_flags：该搜索标志是AV_OPT_SEARCH_*的组合，目前ffmpeg中的搜索标志有两个。如声明中的定义。
            1）AV_OPT_SEARCH_CHILDREN：这个参数用于处理嵌套的情形：传入的obj是一个AVOptions-enabled结构体（也即第一个成员是AVClass*对象，一般obj是一个XXXContext上下文对象），obj对象还有子对象也是一个AVOptions-enabled结构体，那么AV_OPT_SEARCH_CHILDREN搜索标志将会使得优先搜索子对象是否有合适的选项。
           2）AV_OPT_SEARCH_FAKE_OBJ：该标志位表示传入的obj可能不是一个AVOptions-enabled结构体，而是一个相关的AVClass**，一般为了方便用来搜索选项而不需要真实的分配一个上下文对象。

  /**
   * Set all the options from a given dictionary on an object.
   *
   * @param obj a struct whose first element is a pointer to AVClass
   * @param options options to process. This dictionary will be freed and replaced
   *                by a new one containing all options not found in obj.
   *                Of course this new dictionary needs to be freed by caller
   *                with av_dict_free().
   * @param search_flags A combination of AV_OPT_SEARCH_*.
   *
   * @return 0 on success, a negative AVERROR if some option was found in obj,
   *         but could not be set.
   *
   * @see av_dict_copy()
   */
  int av_opt_set_dict2(void *obj, struct AVDictionary **options, int search_flags);

av_opt_set_dict() 源码：

• 所属库：libavutil（lavu）
• 源文件：libavutil/opt.c
• 源码：

  int av_opt_set_dict2(void *obj, AVDictionary **options, int search_flags)
  {
      AVDictionaryEntry *t = NULL;
      AVDictionary    *tmp = NULL;
      int ret = 0;
  
      if (!options)
          return 0;
  
      while ((t = av_dict_get(*options, "", t, AV_DICT_IGNORE_SUFFIX))) {
          ret = av_opt_set(obj, t->key, t->value, search_flags);
          if (ret == AVERROR_OPTION_NOT_FOUND)
              ret = av_dict_set(&tmp, t->key, t->value, 0);
          if (ret < 0) {
              av_log(obj, AV_LOG_ERROR, "Error setting option %s to value %s.\n", t->key, t->value);
              av_dict_free(&tmp);
              return ret;
          }
          ret = 0;
      }
      av_dict_free(options);
      *options = tmp;
      return ret;
  }

  1. 使用av_dict_get()函数迭代选项字典中的option，av_dict_get()分析见 FFMPEG4.1源码分析之 字典类型AVDictionary及其相关APIs
  2.  使用av_opt_set()函数应用选项到obj中。
        2.1）若av_opt_set()函数在obj中未找到选项对应的参数，则返回AVERROR_OPTION_NOT_FOUND。此种情况，该选项信息将被设置到函数内部分配的临时选项字典中。
        2.2）若av_opt_set()函数在obj中找到选项但是设置失败则返回AVERROR(EINVAL)，即-22，表示输入参数值非法。此种情况，函数将清理临时选项字典，并返回错误。
        2.3） av_opt_set()分析见 FFRMPEG4.1源码分析之 av_opt_set()
  3.  如果2中没有出现2.2）的情况，那么入参选项字典中的选项要么是已经成功应用到obj中，要么是存储到临时的选项字典中，此时，释放入参选项字典所占用的内存，并将临时的选项字典传递给入参，从而让函数调用者通过该入参获取到剩余的未应用到obj上的所有选项。