Gstreamer part-progress.txt翻译

进度报告
------------------   
    这篇文章描述了进度报告消息的设计和使用场景。   
    进度消息被post到总线（BUS）上，用来通知应用程序针对PIPELINE进行的异步操作的进度，不应该与异步状态状态改变混同。
    应该满足如下条件：
    -当异步的操作开始和完成时，应用程序能够被通知。
    -应该可以检测通用操作的进度，并整合到GUI中。
    -应用程序应该能够取消正在发生的操作通过执行正常的状态改变。
    -应用程序应该能够等待完成异步的操作。

    考虑到如下的场景：
    -Element能够通知应用程序关于异步的DNS查询和阻塞的网络请求，包括查询的开始和结束。
    -Element异步的打开设备和资源。
    -应用程序应该很自由地执行超时和取消那些阻塞状态改变或者后台不可见的操作。

基本原理
~~~~~~~~~
增加进度通知的机制的主要原因是双重的：

1) 让应用程序能够了解更多的信息，关于当前执行到哪儿了。
     当有定义良好的进度信息状态吗，应用程序能够让用户知道进度的状态。我们至少期待DNS解析、服务器连接和请求的状态码被良好定义。

2)让状态改变是非阻塞的、可取消的。
    当前的状态改变，例如经常因为解析DNS和连接到远程的服务器，从READY或者PAUSED状态阻塞，这些操作经常阻塞主线程并且是不可取消的，从而导致应用程序锁住了。
    我们希望执行状态改变启动一个独立的线程，并以一种可取消的方式执行阻塞操作。当返回到NULL状态，所有阻塞的操作能够迅速被取消。
    我们想让应用程序能够实现他自己的超时机制。例如：当停止一个RTSP流，客户端需要发送TEARDOWN请求给服务器，这个可能由于网络问题花费很长时间，我们想给予应用程序机会来等待这个异步操作的完成。
    进度更新非常类似于缓存消息，用同样的方式，应用程序能够决定在下一个状态改变之前等待缓存处理的完成，在将来用进度消息的方式来实现缓存可能是有意义的。

异步状态改变
~~~~~~~~~~~~~~~~~~~
    Gstreamer当前用GST_STATE_CHANGE_ASYNC来提示应用程序一个状态正在异步的改变。
该返回值的主要目的是让PIPELINE等待preroll，延迟状态改变直到sinks被preroll。
对source进行异步操作，这将自动地强迫sinks异步等待，因为在source产生数据前他们将不能preroll。
    为了不复杂化状态改变，混淆概念，对于与prerolling处理不相关的异步操作，没有实现ASYNC返回值的状态改变。

使用场景
~~~~~~~~~

* RTSP客户端 (还有 HTTP, MMS, ...)
    当client从READY - > PAUSED状态，它打开一个socket，执行DNS查询，返回SDP，协商流信息。所有这些操作阻塞状态改变函数，并且操作不可取消。
    取而代之，一个线程将被启动来执行这个异步操作，状态以返回NO_PREROLL结束。在启动线程前，一个PROGRESS消息被post来标记异步操作的开始。
    当DNS查询完成，连接建立，PROGRESS消息被post来通知应用程序进度。如果失败，错误被post并且PROGRESS CANCELED 消息被post，应用程序然后停止PIPELINE。
    如果没有错误，流建立成功，PROGRESS COMPLETED 被post，线程进入sleep，异步操作完成。
    RTSP协议需要发送TEARDOWN请求给服务器在关闭连接和销毁socket之前。状态改变到READY状态将发送TEARDOWN 请求，提示应用程序一个带PROGRESS阻塞的请求的消息。
   
* 网络性能测量
    DNS查询和连接建立时间能够被测量通过计算相邻的PROGRESS消息的时间间隔。
  
消息
~~~~~~~~

当一个新的PROGRESS 消息被创建，将包含如下字段：

  - "type", GST_TYPE_PROGRESS_TYPE

      - a set of types to define the type of progress

        GST_PROGRESS_TYPE_START: A new task is started in the background
        GST_PROGRESS_TYPE_CONTINUE: The previous tasks completed and a new
                  one continues. This is done so that the application can follow
                  a set of continuous tasks and react to COMPLETE only when the
                  element completely finished.
        GST_PROGRESS_TYPE_CANCELED: A task is canceled by the user.
        GST_PROGRESS_TYPE_ERROR: A task stopped because of an error. In case of
                  an error, an error message will have been posted before.
        GST_PROGRESS_TYPE_COMPLETE: A task completed successfully.

  - "code", G_TYPE_STRING
    一个通用可扩展的字符串，用来表示进度，一些标准的预定义的code被定义了。

  - "text", G_TYPE_STRING

     动作描述字符串.

  - "percent", G_TYPE_INT  between 0 and 100

    Progress of the action as a percentage, the following values are allowed:
      - GST_PROGRESS_TYPE_START always has a 0% value.
      - GST_PROGRESS_TYPE_CONTINUE have a value between 0 and 100
      - GST_PROGRESS_TYPE_CANCELED, GST_PROGRESS_TYPE_ERROR and
        GST_PROGRESS_TYPE_COMPLETE always have a 100% value.

  - "timeout", G_TYPE_INT  in milliseconds

     异步操作的超时时间. -1 if unknown/unlimited..
     This field can be interesting to the application when it wants to display
     some sort of progress indication.

  - ....

     Depending on the code, more fields can be put here.


实现
~~~~~~~~~~~~~~
元素不应该阻塞状态改变的操作。代替的，元素应该post一个合适的带有code和type为
GST_PROGRESS_TYPE_START的消息，然后启动一个线程来执行可以被取消的阻塞调用。
强烈建议：仅仅启动异步操作从READY -> PAUSED状态和之后的状态，不要对NULL -> READY状态。
因为流线程通常从READY -> PAUSED状态时被启动，NULL -> READY状态改变被用来对现存的设备执行阻塞检测。

状态改变时，进度消息需要被post，以便于应用程序在设置完状态后能够迅速的采取合适的动作。
接下来，如果状态发生改变，在线程中执行的操作将被取消，GST_PROGRESS_TYPE_CANCELED将被取消。

应用程序知道阻塞的任务，因为他们能够检索到如下消息：
GST_PROGRESS_TYPE_START messages that didn't complete with a
GST_PROGRESS_TYPE_COMPLETE message, got canceled with a
GST_PROGRESS_TYPE_CANCELED or errored with GST_PROGRESS_TYPE_ERROR.
应用程序能够选择是否等待阻塞的操作还是取消他们。

如果异步操作失败, 错误的消息首先被post，然后是GST_PROGRESS_TYPE_ERROR progress 消息。

code定义
~~~~~~~~~~

标准的codes 定义:

  "open" : A resource is being opened
  "close" : A resource is being closed

  "name-lookup" : A DNS lookup.

  "connect" : A socket connection is established

  "disconnect" : a socket connection is closed

  "request" : A request is sent to a server and we are waiting for a
              reply. This message is posted right before the request is sent
              and completed when the reply has arrived completely.

  "mount" : A volume is being mounted