GioConverterconvert

这是数据转换过程中使用的主要操作。它需要在循环中被多次调用，每次调用都会执行一些工作，即产生一些输出（在outbuf中）或消费一些输入（从inbuf中）或两者都做。如果无法执行任何工作，则返回一个错误。

请注意，单次调用可能不会消耗所有输入（或任何输入）。并且，如果没有给出任何输入，也可能产生输出，这是由于转换器中存储的状态产生的输出。

如果产生了数据或消耗了数据，然后发生错误，则只报告成功的转换，并在下一次调用中返回错误。

完整的转换循环涉及重复调用此方法，每次提供新的输入和输出空间。当inbuf中的数据用尽后，必须设置标志G_CONVERTER_INPUT_AT_END。除非发生一些错误，否则循环将每次返回G_CONVERTER_CONVERTED，直到所有数据都被消耗并且所有输出都被产生，然后返回代替的G_CONVERTER_FINISHED。注意，即使没有设置G_CONVERTER_INPUT_AT_END，也可能返回G_CONVERTER_FINISHED，例如在解压缩转换器中，数据末尾可以从数据中检测到（并且在压缩数据末尾之后可能有其他数据）。

在成功转换一些数据后，将bytes_read设置为从inbuf读取的字节数，将bytes_written设置为指示写入outbuf的字节数。如果有更多数据要输出或消耗（即，除非指定了G_CONVERTER_INPUT_AT_END），则返回G_CONVERTER_CONVERTED，如果没有更多数据要输出，则返回G_CONVERTER_FINISHED。

在错误情况下返回G_CONVERTER_ERROR，并将error相应地设置。某些错误需要特殊处理。

如果没有足够的空间来写入转换后的数据，则返回G_IO_ERROR_NO_SPACE，应用程序应再次调用此函数，并使用更大的outbuf继续。

如果没有足够的输入来完全确定转换应产生什么内容，并且没有设置G_CONVERTER_INPUT_AT_END标志，则返回G_IO_ERROR_PARTIAL_INPUT。例如，在转换文本时遇到不完整的多字节序列，或者当正则表达式匹配到输入的末尾（并且可能匹配更多输入）时，就会发生这种情况。也可能会发生这种情况，当inbuf_size为零，并且没有更多数据要生成时。

当发生这种情况时，应用程序应读取更多输入，然后再次调用该函数。如果进一步输入显示没有更多数据，则使用相同的但带有 G_CONVERTER_INPUT_AT_END 标志的数据重新调用该函数。这可能会导致转换完成，例如在正则表达式匹配的情况下（或者，在字符集转换等实际输入部分的情况下，会再次失败并返回 G_IO_ERROR_PARTIAL_INPUT）。

在 g_converter_convert() 返回 G_CONVERTER_FINISHED 后，转换对象处于无效状态，此时不允许再调用 g_converter_convert()。这时，您只能释放对象或调用 g_converter_reset() 以将其重置到初始状态。

如果设置了标志 G_CONVERTER_FLUSH，则转换会修改为尝试将所有内部状态写入输出。应用程序必须多次设置标志调用函数，当可用输入被消耗且内部状态已生成后，则返回 G_CONVERTER_FLUSHED（或者在真正到达末尾时返回 G_CONVERTER_FINISHED），而不是 G_CONVERTER_CONVERTED。这在某种意义上类似于在输入流结尾发生的情况，但是在数据中间进行。

这在对不同的转换有不同的含义。例如，在压缩转换器中，这意味着我们将所有的压缩状态 Flush 到输出，这样如果您解压压缩数据，您将得到所有的输入数据。但是，由于填充，这样做可能会使最终的文件变得更大。另一个例子是正则表达式转换，如果在 Flush 数据的末尾有一个匹配项，但还有一个潜在的更长匹配项。在非 Flush 的情况下，我们会请求更多的输入，但当我们 Flush 时，我们会将其视为输入的末尾并执行匹配。

并非总是可以进行 Flush（例如，如果字符集转换在多字节序列的中间 Flush）。转换器应尽量产生尽可能多的输出，并在发生错误（通常是 G_IO_ERROR_PARTIAL_INPUT）时返回。

自 2.24 版本起可用