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