--[[----------------------------------------------------------------------------

KSData.lua

--------------------------------------------------------------------------------

ADOBE CONFIDENTIAL
------------------
Copyright 2012 Adobe Systems Incorporated
All Rights Reserved.

NOTICE: All information contained herein is, and remain the property of
Adobe Systems Incorporated and its suppliers, if any. The intellectual and
technical concepts contained herein are proprietary to Adobe Systems
Incorporated and its suppliers and may be covered by U.S. and Foreign
Patents, patents in process, and are protected by trade secret or copyright
law.  Dissemination of this information or reproduction of this material is
strictly forbidden unless prior written permission is obtained from
Adobe Systems Incorporated.

----------------------------------------------------------------------------]]--

	-- WF.core.os
local WFPlatformInfo = require 'WFPlatformInfo'

-- @mark KSData namespace

--[[!
	\class KSData
	\brief 	This namespace represents an ordered binary sequence of bytes.
	The tostring() method converts this to a string.
--]]


--==============================================================================

local KSData = {}

--------------------------------------------------------------------------------
--[[!
	\brief Constructs a KSData object.

	\param value A string containing the binary sequence,
		or another KSData object to copy.

	\return A new KSData object.
--]]

function KSData.make( --[[stringOrKSData]] value )

	-- This function is implemented natively via the direct object defined by
	-- KSData_imp_ClassDesc.

end
	
--------------------------------------------------------------------------------
--[[!
	\brief Reports whether something is a KSData object.

	\param value Any value.

	\return Boolean, true if the value is a KSData object.
--]]

function KSData.isData( --[[anything]] value )

	-- This function is implemented natively in KSData_isData_L.

end
	
--------------------------------------------------------------------------------
--[[!
	\brief Reports the size of a data object.

	\param data The KSData object.

	\return The size of the data, a number of bytes.
--]]

function KSData.length( --[[KSData]] data )

	-- This function is implemented natively in KSData_length_L.

end
	
--------------------------------------------------------------------------------
--[[!
	\brief Constructs a KSData object from the bytes of a file on disk.

	FIXME we are inconsistent about what happens if this can't be done.
	On Mac/iOS, it will throw an error with a message like "Failed to map
	file...".

	\param filePath (string) The file path.

	\return The KSData object.
--]]

function KSData.memoryMappedContentsOfFile( --[[string]] filePath )

	-- This function is implemented natively in
	-- KSData_memoryMappedContentsOfFile_L.

end

--------------------------------------------------------------------------------
--[[!
	\brief Saves the data in this object to a file.
	
	FIXME: What happens if this doesn't work? On Mac/iOS/Android it will fail with an
	error with a message like "failed to write data."

	\param data (KSData) Data object to save.
	\param filePath (string) The file path.

	\return Unique filename.
--]]

function KSData.saveToUniquelyNamedFile( --[[KSData]] data,
										 --[[string]] filePath )

	-- This function is implemented natively in KSData_saveToUniquelyNamedFile_L.

end

--------------------------------------------------------------------------------

if WFPlatformInfo.isAndroid then

	--[[!
		\brief Saves the data in this object to a file respresented by the 
			file descriptor

		\param data (KSData) Data object to save.
		\param fileDescriptor (number) The file descriptor pointing to the destination file.

		\return Unique filename.
	--]]

	function KSData.saveToFileUsingFileDescriptor( --[[KSData]] data,
													--[[number]] fileDescriptor )

		-- This function is implemented natively in KSData_saveToFileUsingFileDescriptor_L.

	end
end

--------------------------------------------------------------------------------

--[[!
	\brief Saves the data in this object to a file. Overwrites any existing data
	
	FIXME: What happens if this doesn't work? On Mac/iOS/Android it will fail with an
	error with a message like "failed to write data."

	\param data (KSData) Data object to save.
	\param filePath (string) The file path.

--]]
function KSData.saveToFile( --[[KSData]] data,
								 --[[string]] filePath )

	-- This function is implemented natively in KSData_saveToFile_L.

end
	
--==============================================================================

-- class methods

--------------------------------------------------------------------------------
--[[!
	\brief Digests the data in this object.

	\param algorithm The digest algorithm, as string. For supported
		values, see WFCrypto.

	\return The digest as a hexidecimal string.
	\return The digest as a raw binary string.
--]]

function KSData:digest( --[[string]] algorithm )

	-- This function is implemented natively in KSData_digest_L.

end

--------------------------------------------------------------------------------
--[[!
	\brief Releases the memory for this object.
	
	All subsequent calls to this object fail, except KSData.length( data ),
	which returns 0.
--]]

function KSData:close()

	-- This function is implemented natively in KSData.

end


--==============================================================================

-- KSData is implemented natively -- the previous value of the local KSData
-- was for documentation purposes.

local KSDataImp = require 'KSDataImp'

for k in pairs( KSData ) do
	KSData[ k ] = KSDataImp[ k ]
end

--------------------------------------------------------------------------------

-- Lua based KSData functions

--------------------------------------------------------------------------------

local checkerRegistered = false

function KSData.registerArgumentChecker()

	if not checkerRegistered then
		local WFArguments = require 'WFArguments'
		WFArguments.registerChecker( 'KSData', KSData.isData )
	end
	checkerRegistered = true

end

--==============================================================================

return KSData
