PhoneGap API幫助文檔翻譯—Capture (採集)

“	提供對設備音頻、圖像和視頻採集功能的訪問。

對象：

Capture
CaptureAudioOptions
CaptureImageOptions
CaptureVideoOptions
CaptureCB
CaptureErrorCB
ConfigurationData
MediaFile
MediaFileData

方法：

capture.captureAudio
capture.captureImage
capture.captureVideo
MediaFile.getFormatData

範圍：

capture對象被分配給navigator.device對象，因此作用域爲全局範圍。

簡單的範例：

// 全局範圍的capture對象	
var capture = navigator.device.capture;

屬性：

supportedAudioModes：當前設備所支持的音頻錄製格式。（ConfigurationData[] 類型）
supportedImageModes：當前設備所支持的拍攝圖像尺寸及格式。（ConfigurationData[] 類型）
supportedVideoModes：當前設備所支持的拍攝視頻分辨率及格式。（ConfigurationData[] 類型）

方法：

capture.captureAudio：啓動設備錄製音頻剪輯的音頻錄製應用程序。
capture.captureImage：啓動設備拍攝照片的攝像頭應用程序。
capture.captureVideo：啓動設備拍攝視頻的視頻錄製應用程序。

支持的平臺：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

capture.captureAudio

“

啓動錄音機應用程序並返回採集的音頻剪輯文件。

navigator.device.capture.captureAudio(CaptureCB captureSuccess, 
		CaptureErrorCB captureError, [CaptureAudioOptions options] );

說明：

該方法通過設備默認的音頻錄製應用程序開始一個異步操作以採集音頻錄製。該操作允許設備用戶在一個會話中同時採集多個錄音。

當用戶退出音頻錄製應用程序，或系統到達CaptureAudioOptions的limit參數所定義的最大錄製數時都會停止採集操作。如果沒有設置limit參數的值，則使用其默認值1，也就是說當用戶錄製好一個音頻剪輯後採集操作就會終止。

當採集操作結束後，系統會調用CaptureCB回調函數，傳遞一個包含所有採集到的音頻剪輯文件的MediaFile對象數組。如果用戶在完成一個音頻剪輯採集之前終止採集操作，系統會調用CaptureErrorCB回調函數，並傳遞一個包含CaptureError.CAPTURE_NO_MEDIA_FILES錯誤代碼的CaptureError對象。

支持的平臺：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的範例：

// 採集操作成功完成後的回調函數
var captureSuccess = function(mediaFiles) { 
	var i, path, len;
	for (i = 0, len = mediaFiles.length; i < len; i += 1) {
		path = mediaFiles[i].fullPath; 	
		// 對文件進行感興趣的操作
	} 
};  
	
// 採集操作出錯後的回調函數
var captureError = function(error) { 
	navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); 
};  
	
// 開始採集音頻
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});

完整的範例：

<!DOCTYPE html>
<html>
<head>
<title>Capture Audio</title>  
	
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script> 
<script type="text/javascript" charset="utf-8" src="json2.js"></script> 
<script type="text/javascript" charset="utf-8"> 

	// 採集操作成功完成後的回調函數
	function captureSuccess(mediaFiles) { 
		var i, len; 
		for (i = 0, len = mediaFiles.length; i < len; i += 1) {
			uploadFile(mediaFiles[i]); 
		} 
	} 
	
	// 採集操作出錯後的回調函數
	function captureError(error) { 
		var msg = 'An error occurred during capture: ' + error.code;
		navigator.notification.alert(msg, null, 'Uh oh!'); 
	} 
	
	// “Capture Audio”按鈕點擊事件觸發函數
	function captureAudio() { 
	
		// 啓動設備的音頻錄製應用程序,  
		// 允許用戶最多采集2個音頻剪輯
		navigator.device.capture.captureAudio(captureSuccess, captureError, {limit: 2});
	} 
	 
	// 上傳文件到服務器 
	function uploadFile(mediaFile) {
		var ft = new FileTransfer(), 
		path = mediaFile.fullPath, 
		name = mediaFile.name; 
		ft.upload(path,
				"http://my.domain.com/upload.php",
				function(result) { 
					console.log('Upload success: ' + result.responseCode); 
					console.log(result.bytesSent + ' bytes sent'); 
				}, 
				function(error) { 
					console.log('Error uploading file ' + path + ': ' + error.code); 
				}, 
				{ fileName: name });  
	}  
	
</script>
</head>
<body>
	<button onclick="captureAudio();">Capture Audio</button>
</body>
</html>

BlackBerry WebWorks的特異情況：

在BlackBerry WebWorks上，PhoneGap會嘗試啓動RIM提供的Voice Notes Recorder應用程序來採集音頻錄製。如果設備沒有安裝該應用程序，開發者會收到一個CaptureError.CATURE_NOT_SUPPORTED錯誤代碼。

iOS的特異情況：

iOS沒有默認的音頻錄製應用程序，因此僅提供一個簡單的用戶界面。

CaptureAudioOptions

“

封裝音頻採集的配置選項。

屬性：

limit：在單個採集操作期間能夠記錄的音頻剪輯數量最大值，必須設定爲大於等於1（默認值爲1）。
drration：一個音頻剪輯的最長時間，單位爲秒。
mode：選定的音頻模式，必須設定爲capture.supportedAudioModes枚舉中的值。

簡單的範例：

// 限制採集上限爲3個媒體文件，每個文件不超過10秒
var options = { limit: 3, duration: 10 };
	
navigator.device.capture.captureAudio(captureSuccess, captureError, options);

Android的特異情況：

不支持duration參數，無法通過程序限制錄製長度。
不支持mode參數，無法通過程序修改音頻錄製格式。使用自適應多速率（AMR）格式（audio/amr）進行音頻錄製編碼。

BlackBerry WebWorks的特異情況：

不支持duration參數，無法通過程序限制錄製長度。
不支持mode參數，無法通過程序修改音頻錄製格式。使用自適應多速率（AMR）格式（audio/amr）進行音頻錄製編碼。

iOS的特異情況：

不支持limit參數，每次調用只能創建一個錄製。
不支持mode參數，無法通過程序修改音頻錄製格式。使用波形音頻（WAV）格式（audio/wav）進行音頻錄製編碼。

capture.captureImage

“

開啓攝像頭應用程序，返回採集到的圖像文件信息。

navigator.device.capture.captureImage( 
CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options]
);

說明：

該方法通過設備的攝像頭應用程序開始一個異步操作以採集圖像。該操作允許設備用戶在一個會話中同時採集多個圖像。

當用戶退出攝像頭應用程序，或系統到達CaptureImageOptions的limit參數所定義的最大圖像數時都會停止採集操作。如果沒有設置limit參數的值，則使用其默認值1，也就是說當用戶採集到一個圖像後採集操作就會終止。

當採集操作結束後，系統會調用CaptureCB回調函數，傳遞一個包含每個採集到的圖像文件的MediaFile對象數組。如果用戶在完成一個圖像採集之前終止採集操作，系統會調用CaptureErrorCB回調函數，並傳遞一個包含CaptureError.CAPTURE_NO_MEDIA_FILES錯誤代碼的CaptureError對象。

支持的平臺：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的範例：

// 採集操作成功完成後的回調函數
var captureSuccess = function(mediaFiles) { 
	var i, path, len; 
	for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
		path = mediaFiles[i].fullPath;
		// 對文件進行感興趣的操作
	} 
}; 

// 採集操作出錯後的回調函數
var captureError = function(error) { 
	navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); 
}; 

// 開始採集圖像
navigator.device.capture.captureImage(captureSuccess, captureError, {limit:2});

完整的範例：

<!DOCTYPE html>
<html>
<head>	
<title>Capture Image</title> 

<script type="text/javascript" charset="utf-8" src="phonegap.js"></script> 
<script type="text/javascript" charset="utf-8" src="json2.js"></script> 
<script type="text/javascript" charset="utf-8"> 

	// 採集操作成功完成後的回調函數
	function captureSuccess(mediaFiles) { 
		var i, len; 
		for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
			uploadFile(mediaFiles[i]); 
		}      
	} 
	
	// 採集操作出錯後的回調函數
	function captureError(error) { 
		var msg = 'An error occurred during capture: ' + error.code; 
		navigator.notification.alert(msg, null, 'Uh oh!'); 
	} 
	
	// “Capture Image”按鈕點擊事件觸發函數
	function captureImage() {
		// 啓動設備的攝像頭應用程
		// 允許用戶最多采集2個圖像
		navigator.device.capture.captureImage(captureSuccess, captureError, {limit: 2});
	} 
	
	// 上傳文件到服務器
	function uploadFile(mediaFile) {
		var ft = new FileTransfer(),
			path = mediaFile.fullPath, 
			name = mediaFile.name; 
	
		ft.upload(path,"http://my.domain.com/upload.php", 
			function(result) { 
				console.log('Upload success: ' + result.responseCode);
				console.log(result.bytesSent + ' bytes sent'); 
			}, 
			function(error) { 
				console.log('Error uploading file ' + path + ': ' + error.code); 
			}, 
			{ fileName: name });
	}  

</script>
</head>
<body>
	<button onclick="captureImage();">Capture Image</button>
</body>
</html>

CaptureImageOptions

“

封裝圖像採集的配置選項。

屬性：

limit：在單個採集操作期間能夠採集的圖像數量最大值，必須設定爲大於等於1（默認值爲1）。
mode：選定的圖像模式，必須設定爲capture.supportedImageModes枚舉中的值。

簡單的範例：

// 最多采集3幅圖像
var options = { limit: 3 };

navigator.device.capture.captureImage(captureSuccess, captureError, options);

Android的特異情況：

不支持mode參數，無法通過程序修改圖像的大小和格式。不過設備用戶可以修改圖像的大小，圖像會以JPEG格式(image/jpeg)存儲。

BlackBerry WebWorks的特異情況：

不支持mode參數，無法通過程序修改圖像的大小和格式。不過設備用戶可以修改圖像的大小，圖像會以JPEG格式(image/jpeg)存儲。

iOS的特異情況：

不支持limit參數，每調用一次採集一幅圖像。
不支持mode參數，無法通過程序修改圖像的大小和格式。圖像會以JPEG格式(image/jpeg)存儲。

capture.captureVideo

“

開啓視頻錄製應用程序，返回採集到的視頻剪輯文件信息。

// 最多采集3幅圖像
var options = { limit: 3 };

navigator.device.capture.captureImage(captureSuccess, captureError, options);

說明：

該方法通過設備的視頻錄製應用程序開始一個異步操作以採集視頻錄製。該操作允許設備用戶在一個會話中同時採集多個視頻錄製。

當用戶退出視頻錄製應用程序，或系統到達CaptureVideoOptions的limit參數所定義的最大錄製數時都會停止採集操作。如果沒有設置limit參數的值，則使用其默認值1，也就是說當用戶錄製到一個視頻剪輯後採集操作就會終止。

當採集操作結束後，系統會調用CaptureCB回調函數，傳遞一個包含每個採集到的視頻剪輯文件的MediaFile對象數組。如果用戶在完成一個視頻剪輯採集之前終止採集操作，系統會調用CaptureErrorCB回調函數，並傳遞一個包含CaptureError.CAPTURE_NO_MEDIA_FILES錯誤代碼的CaptureError對象。

支持的平臺：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的範例：

// 採集操作成功完成後的回調函數
var captureSuccess = function(mediaFiles) { 
	var i, path, len; 
	for (i = 0, len = mediaFiles.length; i < len; i += 1) { 	
		path = mediaFiles[i].fullPath; 
		// 對文件進行感興趣的操作
	} 
}; 

// 採集操作出錯後的回調函數 
var captureError = function(error) { 
	navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); 
}; 

// 開始採集視頻
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});

完整的範例：

<!DOCTYPE html>
<html>
<head>
<title>Capture Video</title> 

<script type="text/javascript" charset="utf-8" src="phonegap.js"></script> 
<script type="text/javascript" charset="utf-8" src="json2.js"></script> 
<script type="text/javascript" charset="utf-8"> 

	// 採集操作成功完成後的回調函數
	function captureSuccess(mediaFiles) { 
		var i, len; 
		for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
			uploadFile(mediaFiles[i]); 
		}        
	} 

	// 採集操作出錯後的回調函數 
	function captureError(error) { 
		var msg = 'An error occurred during capture: ' + error.code; 
		navigator.notification.alert(msg, null, 'Uh oh!'); 
	} 
 
	// “Capture Video”按鈕點擊事件觸發函數
	function captureVideo() {  
		// 啓動設備的視頻錄製應用程序,
		// 允許用戶最多采集2個視頻剪輯 
		navigator.device.capture.captureVideo(captureSuccess, captureError, {limit: 2}); 
	} 

	// 上傳文件到服務器
	function uploadFile(mediaFile) { 
		var ft = new FileTransfer(), 
			path = mediaFile.fullPath, 
			name = mediaFile.name; 

		ft.upload(path,"http://my.domain.com/upload.php", 
			function(result) { 
				console.log('Upload success: ' + result.responseCode); 
				console.log(result.bytesSent + ' bytes sent'); 
			}, 
			function(error) { 
				console.log('Error uploading file ' + path + ': ' + error.code); 
			}, 
			{ fileName: name });    
	}  

</script>
</head>
<body>
	<button onclick="captureVideo();">Capture Video</button>
</body>
</html>

BlackBerry WebWorks 的特異情況：

在BlackBerry WebWorks上，PhoneGap會嘗試啓動RIM提供的Video Recorder應用程序來採集視頻錄製。如果設備沒有安裝該應用程序，開發者會收到一個CaptureError.CATURE_NOT_SUPPORTED錯誤代碼。

CaptureVideoOptions

“

封裝視頻採集的配置選項。

屬性：

limit：在單個採集操作期間能夠採集的視頻剪輯數量最大值，必須設定爲大於等於1（默認值爲1）。
drration：一個視頻剪輯的最長時間，單位爲秒。
mode：選定的視頻採集模式，必須設定爲capture.supportedVideoModes枚舉中的值。

簡單的範例：

// 最多采集3個視頻剪輯
var options = { limit: 3 };

navigator.device.capture.captureVideo(captureSuccess, captureError, options);

Android的特異情況：

不支持duration參數，無法通過程序限制錄製長度。
不支持mode參數，無法通過程序修改視頻的大小和格式。不過，設備用戶可以修改這些參數，默認情況下視頻會以3GPP格式(video/3gpp)存儲。

BlackBerry WebWorks的特異情況：

不支持duration參數，無法通過程序限制錄製長度。
不支持mode參數，無法通過程序修改視頻的大小和格式。不過，設備用戶可以修改這些參數，默認情況下視頻會以3GPP(video/3gpp)格式存儲。

iOS的特異情況：

不支持limit參數，每調用一次採集一個視頻。
不支持duration參數，無法通過程序限制錄製長度。
不支持mode參數，無法通過程序修改視頻的大小和格式。默認情況下視頻會以MOV(video/3gpp)格式存儲。

CaptureCB

“

媒體採集成功後調用的回調函數。

function captureSuccess( MediaFile[] mediaFiles ) { ... }

說明：

當完成一個成功的採集操作後會調用該函數。這意味着已經採集到一個媒體文件，同時要麼用戶已經退出媒體採集應用程序，要麼已經到達採集數量上限。

每個MediaFile對象都指向一個採集到的媒體文件。

簡單的範例：

// 採集操作成功完成後的回調函數
function captureSuccess(mediaFiles) {
   	var i, path, len;
   	for (i = 0, len = mediaFiles.length; i < len; i += 1) {
	   	path = mediaFiles[i].fullPath;
	   	//對文件進行感興趣的操作
	}
}

CaptureErrorCB

“

媒體採集操作發生錯誤後調用的回調函數。

function captureError( CaptureError error ) { ... }

說明：

出現以下情況會調用該函數：試圖在採集應用程序繁忙時啓動媒體採集操作而引起錯誤、採集操作正在工作時出現錯誤、用戶在沒有任何媒體文件採集完成前取消採集操作。

該函數調用時會傳遞一個包含相應錯誤代碼的CaptureError對象。

簡單的範例：

// 採集操作出錯後的回調函數
var captureError = function(error) {
	navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
}

ConfigurationData

“

封裝設備支持的媒體採集參數集。

說明：

該對象用於描述設備所支持的媒體採集模式，配置數據包括MIME類型和採集尺寸（適用於視頻和圖像採集）。

MIME類型應該符合RFC2046規範，例如：

video/3gpp
video/quicktime
image/jpeg
audio/amr
audio/wav

屬性：

type：用小寫ASCII編碼字符串表示的媒體類型。（DOMString格式）
height：用像素表示的圖像或視頻高度，音頻剪輯爲0。（數字類型）
width：用像素表示的圖像或視頻寬度，音頻剪輯爲0。（數字類型）

簡單的範例：

// 獲得支持的圖像模式
var imageModes = navigator.device.capture.supportedImageModes;

// 選擇最高水平分辨率的模式
var width = 0;
var selectedmode;
foreach (var mode in imageModes) {
	if (mode.width > width) {
	   	width = mode.width;
	   	selectedmode = mode;
   	}
}

沒有任何一個平臺支持，所有配置數據數組都爲空。

MediaFile

“

封裝採集到的媒體文件的屬性。

屬性：

name：不含路徑信息的文件名。（DOMString類型）
fullPath：包含文件名的文件全路徑。（DOMString類型）
type： MIME類型。（DOMString類型）
lastModifiesDate：文件最後修改的日期和時間。（日期類型）
size：以字節數表示的文件大小。（數字類型）

方法：

MediaFile.getFormatData：獲取媒體文件的格式信息

MediaFile.getFormatData

“

獲取採集到的媒體文件的格式信息。

mediaFile.getFormatData(  
MediaFileDataSuccessCB successCallback,  
	[MediaFileDataErrorCB errorCallback] 
)

說明：

該方法通過異步方式嘗試獲取媒體文件的格式信息。獲取成功的情況下該方法會調用MediaFileDataSuccessCB回調並傳遞一個MediaFileData對象，嘗試失敗的情況下該方法會調用MediaFileDataErrorCB回調。

支持的平臺：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

BlackBerry WebWorks的特異情況：

沒有提供媒體文件格式信息的API，因此，所有MediaFileData對象都會返回默認值。參考MediaFileData文檔。

Android的特異情況：

獲取媒體文件格式信息的API受到限制，因此，不是所有的MediaFileData屬性都支持。參考MediaFileData文檔。

iOS的特異情況：

獲取媒體文件格式信息的API受到限制，因此，不是所有的MediaFileData屬性都支持。參考MediaFileData文檔。

MediaFileData

“

封裝媒體文件的格式信息。

屬性：

codecs：音頻及視頻內容的實際格式。（DOMString類型）
bitrate：文件內容的平均比特率。對於圖像文件，屬性值爲0。（數字類型）
height：用像素表示的圖像或視頻高度，音頻剪輯的該屬性值爲0。（數字類型）
width：用像素表示的圖像或視頻的寬度，音頻剪輯的該屬性值爲0。（數字類型）
duration：以秒爲單位的視頻或音頻剪輯時長，圖像文件的該屬性值爲0。（數字類型）

BlackBerry WebWorks的特異情況：

沒有提供媒體文件格式信息的API，因此MediaFile.getFormatData方法返回的MediaFileData對象包含以下默認值：

codecs：不支持，該屬性始終爲空。
bitrate：不支持，該屬性始終爲0。
heigh：不支持，該屬性始終爲0。
width：不支持，該屬性始終爲0。
duration：不支持，該屬性始終爲0。

Android的特異情況：

MediaFileData屬性的支持情況如下：

codecs：不支持，該屬性始終爲空。
bitrate：不支持，該屬性始終爲0。
height：支持（僅限圖像或視頻文件）。
width：支持（僅限圖像或視頻文件）。
duration：支持（僅限音頻或視頻文件）。

iOS的特異情況：

MediaFileData屬性的支持情況如下：

codecs：不支持，該屬性始終爲空。
bitrate：iOS4設備上僅支持音頻，對於圖像和視頻此屬性值爲0。
height：支持（僅限圖像或視頻文件）。
width：支持（僅限圖像或視頻文件）。
duration：支持（僅限音頻或視頻文件）。

更多信息參考：

PhoneGap中國：www.phonegap.cn

中文討論組：groups.google.com/group/PhoneGapCN

PhoneGap API幫助文檔翻譯—Capture (採集)

公司剛入職了一名 Java 中級開發，短短 4 行代碼居然湊齊了 3 個 bug！我哭了~~

公衆號5月C#/.NET熱文一覽

git 下載大陸鏡像地址

PhoneGap API幫助文檔翻譯—Events（事件）

PhoneGap API幫助文檔翻譯—File（文件）

PhoneGap API幫助文檔翻譯—Geolocation（地理位置）

PhoneGap API幫助文檔翻譯—Compass(羅盤)

PhoneGap API幫助文檔翻譯—Connection（連接）

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結