> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XAppCaptureRecordTimespan

> XAppCaptureRecordTimespan

# XAppCaptureRecordTimespan

進行 GameDVR 錄製。不會有任何 UI 指出正在進行此類錄製。使用者無法存取此錄製內容。任何時間最多只能進行 2 個此類錄製。一旦已進行 2 個錄製，就必須呼叫 [XAppCaptureCloseLocalStream](/zh-TW/reference/system/xappcapture/functions/xappcapturecloselocalstream) 來關閉並刪除錄製，才能進行另一個錄製。這可用來擷取過去或未來的活動。

## 語法

```cpp theme={null}
HRESULT XAppCaptureRecordTimespan(
  const SYSTEMTIME * startTimestamp,
  uint64_t durationInMilliseconds,
  XAppCaptureLocalResult * result
)
```

### 參數

*startTimestamp* \_In\_opt\_\
類型：const SYSTEMTIME \*

開始錄製的時間戳記。此參數可以是 null，在此情況下，系統會自動將開始時間計算為過去 *durationInMilliseconds* 的時間點，而錄製內容將包含過去的活動。

*durationInMilliseconds* \_In\_\
類型：uint64\_t

錄製長度 (毫秒)。

*result* \_Out\_\
類型：XAppCaptureLocalResult \*

函式完成時，包含擷取結果。如需如何讀取所產生的錄製內容，請參閱 [XAppCaptureReadLocalStream](/zh-TW/reference/system/xappcapture/functions/xappcapturereadlocalstream)。

### 傳回值

類型：HRESULT

函式結果。

如果使用者的 GameDVR 設定禁止遊戲進行擷取，此函式將傳回 E\_ACCESSDENIED。

## 備註

有兩種方式可傳入 *startTimestamp* 參數來錄製過去的活動。

第一種方式是傳入 null。系統會自動計算時間戳記，並錄製從現在往回 *durationInMilliseconds* 長度的過去活動。

<Note>當配置的空間填滿時，將刪除較舊的剪輯，為新剪輯騰出空間。請使用 [PLS](/zh-TW/reference/system/xpersistentlocalstorage/xpersistentlocalstorage_members) (Persistent Local Storage)、connected storage (例如 [XGameSave](/zh-TW/reference/system/xgamesave/xgamesave_members) 或 [XGameSaveFiles](/zh-TW/reference/system/xgamesavefiles/xgamesavefiles_members)) 或類似的儲存系統，以在設定的期間內保留剪輯。</Note>

```cpp theme={null}
XAppCaptureLocalResult appCaptureLocalResult = { 0 };
uint64_t durationInMs = 5000; /* 5 seconds, for example */

if (SUCCEEDED(XAppCaptureRecordTimespan(nullptr, durationInMs, &appCaptureLocalResult))) // record the past 5000ms (startTimestamp is calculated automatically)
{
    appLog.AddLog("StartTimestamp: %llu, Duration (ms): %llu, File Size (bytes): %llu, Width: %d, Height: %d, Encoding: %d, Color Format: %d\n", appCaptureLocalResult.clipStartTimestamp, appCaptureLocalResult.durationInMilliseconds, appCaptureLocalResult.fileSizeInBytes,
        appCaptureLocalResult.width, appCaptureLocalResult.height, appCaptureLocalResult.encoding, appCaptureLocalResult.colorFormat);
}
```

第二種方式是您必須計算所需的開始時間戳記：將 SYSTEMTIME 或 FILETIME 轉換為 ULARGE\_INTEGER，執行必要的運算，然後將 ULARGE\_INTEGER 轉換回 SYSTEMTIME。

```cpp theme={null}
void SubtractMsDurationFromFileTimeToULarge(_In_ FILETIME* pFileTime, _In_ uint64_t durationInMs, _Out_ ULARGE_INTEGER* pUlResultingTime)
{
    ULARGE_INTEGER fileTimeAsUlarge;

    fileTimeAsUlarge.LowPart = pFileTime->dwLowDateTime;
    fileTimeAsUlarge.HighPart = pFileTime->dwHighDateTime;

    // Convert ms to 100 ns intervals, the convention used by FILETIME
    pUlResultingTime->QuadPart = fileTimeAsUlarge.QuadPart - (durationInMs * 10000LL);
}

void ULargeToSystemTime(_In_ ULARGE_INTEGER ulInputTime, _Out_ SYSTEMTIME* pOutputTime)
{
    FILETIME inputAsFiletime;

    inputAsFiletime.dwLowDateTime = ulInputTime.LowPart;
    inputAsFiletime.dwHighDateTime = ulInputTime.HighPart;

    FileTimeToSystemTime(&inputAsFiletime, pOutputTime);
}

void YourFunction()
{
    XAppCaptureLocalResult appCaptureLocalResult = { 0 }; 
    uint64_t durationInMs = 8000; /* 8 seconds, for example */
    FILETIME now;
    ULARGE_INTEGER calculatedStartTimestamp;
    SYSTEMTIME startTimestampAsSystemTime;
    XAppCaptureVideoCaptureSettings captureSettings = { 0 };

    GetSystemTimeAsFileTime(&now);
    SubtractMsDurationFromFileTimeToULarge(&now, durationInMs, &calculatedStartTimestamp);
    ULargeToSystemTime(calculatedStartTimestamp, &startTimestampAsSystemTime);
    
    if (SUCCEEDED(XAppCaptureGetVideoCaptureSettings(&captureSettings)) && captureSettings.isCaptureByGamesAllowed && (captureSettings.maxRecordTimespanDurationInMs >= durationInMs)){
        if (SUCCEEDED(XAppCaptureRecordTimespan(&startTimestampAsSystemTime, durationInMs, &appCaptureLocalResult))) // record 8000ms starting from 8000ms before now (calculated manually)
        {
            appLog.AddLog("StartTimestamp: %llu, Duration (ms): %llu, File Size (bytes): %llu, Width: %d, Height: %d, Encoding: %d, Color Format: %d\n", appCaptureLocalResult.clipStartTimestamp, appCaptureLocalResult.durationInMilliseconds, appCaptureLocalResult.fileSizeInBytes,
                appCaptureLocalResult.width, appCaptureLocalResult.height, appCaptureLocalResult.encoding, appCaptureLocalResult.colorFormat);
        }
    }
}
```

XAppCaptureRecordTimespan 也可以藉由將 *startTimestamp* 指定為目前的系統時間，來錄製接下來 *durationInMilliseconds* 毫秒的活動。

```cpp theme={null}
XAppCaptureLocalResult appCaptureLocalResult = { 0 }; 
uint64_t durationInMs = 10000; /* 10 seconds, for example */
SYSTEMTIME nowStartTimestamp;
XAppCaptureVideoCaptureSettings captureSettings = { 0 };

GetSystemTime(&nowStartTimestamp);

if (SUCCEEDED(XAppCaptureGetVideoCaptureSettings(&captureSettings)) && captureSettings.isCaptureByGamesAllowed){
    if (SUCCEEDED(XAppCaptureRecordTimespan(&nowStartTimestamp, durationInMs, &appCaptureLocalResult))) // record the next 10 seconds starting now
    {
        appLog.AddLog("StartTimestamp: %llu, Duration (ms): %llu, File Size (bytes): %llu, Width: %d, Height: %d, Encoding: %d, Color Format: %d\n", appCaptureLocalResult.clipStartTimestamp, appCaptureLocalResult.durationInMilliseconds, appCaptureLocalResult.fileSizeInBytes,
            appCaptureLocalResult.width, appCaptureLocalResult.height, appCaptureLocalResult.encoding, appCaptureLocalResult.colorFormat);
    }
}
```

請參閱 [XAppCaptureLocalResult](/zh-TW/reference/system/xappcapture/structs/xappcapturelocalresult) 和 [XAppCaptureReadLocalStream](/zh-TW/reference/system/xappcapture/functions/xappcapturereadlocalstream)

## 需求

**標頭：** XAppCapture.h

**程式庫：** xgameruntime.lib

**支援的平台：** XBOX One 系列主機和 XBOX Series 主機

## 另請參閱

[XAppCapture 成員](/zh-TW/reference/system/xappcapture/xappcapture_members)


## Related topics

- [XAppCaptureRecordTimespan](/reference/system/xappcapture/functions/xappcapturerecordtimespan.md)
- [XAppCaptureLocalResult](/reference/system/xappcapture/structs/xappcapturelocalresult.md)
- [XAppCaptureReadLocalStream](/reference/system/xappcapture/functions/xappcapturereadlocalstream.md)