conafilesystem.h

以前做NOKIA手机与PC通信时所参考的源代码,里面包括两个程序,一个是手机文件夹浏览源码,另一个手机SIS安装程序.

/*
==============================================================================
* File System API 3.2
*
Filename    : CONAFileSystem.h
Description : File System API functions
Version     : 3.2

Copyright (c) 2005-2007 Nokia Corporation.
This software, including but not limited to documentation and any related 
computer programs ("Software"), is protected by intellectual property rights 
of Nokia Corporation and/or its licensors. All rights are reserved. By using 
the Software you agree to the terms and conditions hereunder. If you do not 
agree you must cease using the software immediately.
Reproducing, disclosing, modifying, translating, or distributing any or all 
of the Software requires the prior written consent of Nokia Corporation. 
Nokia Corporation retains the right to make changes to the Software at any 
time without notice.

A copyright license is hereby granted to use of the Software to make, publish, 
distribute, sub-license and/or sell new Software utilizing this Software. 
The Software may not constitute the primary value of any new software utilizing 
this software. No other license to any other intellectual property rights of 
Nokia or a third party is granted. 

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS 
OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF NON-INFRINGEMENT, 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL
NOKIA CORPORATION BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, 
OR CONSEQUENTIAL LOSS OR DAMAGES, INCLUDING BUT NOT LIMITED TO, LOST PROFITS 
OR REVENUE, LOSS OF USE, COST OF SUBSTITUTE PROGRAM, OR LOSS OF DATA OR EQUIPMENT 
ARISING OUT OF THE USE OR INABILITY TO USE THE MATERIAL, EVEN IF 
NOKIA CORPORATION HAS BEEN ADVISED OF THE LIKELIHOOD OF SUCH DAMAGES OCCURRING. 
==============================================================================
*/
#ifndef _CONAFILESYSTEM_H_
#define _CONAFILESYSTEM_H_

///////////////////////////////////////////////////////////
// PC Connectivity API
///////////////////////////////////////////////////////////
	#ifndef PCCS_FSAPI
		#define PCCS_FSAPI DWORD STDAPICALLTYPE
		#define PCCS_FSAPI_EX(type) type STDAPICALLTYPE
	#endif
///////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////
// File System API definitions
///////////////////////////////////////////////////////////
	#include "FSAPIDefinitions.h"
///////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////
// File System API functions
///////////////////////////////////////////////////////////

	//=========================================================
	// File System API versions 
	//
		#define FSAPI_VERSION_30		30
		#define FSAPI_VERSION_31		31
		#define FSAPI_VERSION_32		32
	//=========================================================

	//=========================================================
	// FSAPI_Initialize
	//
	// Description:
	//	FSAPI_Initialize initializes the API. This must be called once and before any other FSAPI call!
	//  It's not allowed to call this function like this 
	//		FSAPI_Initialize(FSAPI_GetAPIVersion(), NULL);
	//	You must call it like this
	//		FSAPI_Initialize(FSAPI_VERSION_32, NULL);
	//
	// Parameters:
	//	dwAPIVersion	[in] FSAPI version requested.
	//	pdwParam		[in] Reserved for future use. Must be NULL.
	//
	// Return values:
	//
		PCCS_FSAPI FSAPI_Initialize(DWORD dwAPIVersion, DWORD* pdwParam);
	//=========================================================

	//=========================================================
	// FSAPI_Terminate
	//
	// Description:
	//	FSAPI_Terminate terminates the API. This must be called once and as the last FSAPI call!
	//
	// Parameters:
	//	pdwParam		[in] Reserved for future use. Must be NULL.
	//
	// Return values:
	//
		PCCS_FSAPI FSAPI_Terminate(DWORD* pdwParam);
	//=========================================================

	//=========================================================
	// FSAPI_GetAPIVersion
	//
	// Description:
	//	Returns currently installed version of this FSAPI.
	//
	// Parameters:
	//
	// Return values:
	//	API version number. 
	//
		PCCS_FSAPI FSAPI_GetAPIVersion();
	//=========================================================

	//=========================================================
	// CONAOpenFS
	//
	// Description:
	//	CONAOpenFS opens a file system (FS) connection to the target 
	//	device. The function sets the FS Connection handle, which 
	//	identifies different client connections. It will be placed 
	//	into the given pointer. 
	//	
	//	If the media type is CONAPI_MEDIA_ALL, the System selects 
	//	the used media type automatically by applying the following rule:
	//	If there is an open FS connection to the device, it will be used. 
	//	Otherwise the System tries to open the FS connection in the 
	//	following order: USB, Serial, Irda and BT (if the device is 
	//	connected via medias). The function also sets the DeviceID, 
	//	which can be used to identify the used media type.
	//	
	//	If the Serial Number is an empty string, the function tries to 
	//	open the FS connection by using the pdwDeviceID parameter. The 
	//	pdwMedia parameter is not used in the exemplary case.
	//
	// Parameters:
	//	pstrSerialNumber [in]     The device's serial number, which must be set.
	//	pdwMedia		 [in,out] In: Media type, which defines the target
	//								 media for the Device's FS connection.
	//							  Out:If the value is CONAPI_MEDIA_ALL, the 
	//								 target media is selected automatically 
	//								 and the used media type is returned.
	//	phFSHandle		 [out]	  Handle to the opened FS connection
	//	pdwDeviceID		 [in,out] In: Device ID. Used only when the Serial 
	//								 number is empty string.
	//							  Out: Returned Device ID value of the connected device.
	//
	// Return values:
	// CONA_OK
	// ECONA_DEVICE_NOT_FOUND
	// ECONA_NO_CONNECTION_VIA_MEDIA
	// ECONA_NOT_SUPPORTED_DEVICE
	// ECONA_CONNECTION_FAILED
	// ECONA_CONNECTION_BUSY
	// ECONA_CONNECTION_LOST
	// ECONA_FAILED_TIMEOUT
	// ECONA_INVALID_POINTER
	// ECONA_NOT_INITIALIZED
	// ECONA_NOT_SUPPORTED_MANUFACTURER
	// ECONA_NOT_ENOUGH_MEMORY
	// ECONA_UNKNOWN_ERROR
	//
		PCCS_FSAPI CONAOpenFS( const WCHAR* pstrSerialNumber,
							 DWORD*	pdwMedia,
							 FSHANDLE* phFSHandle,
							 DWORD*	pdwDeviceID );
	//=========================================================

	//=========================================================
	// CONACloseFS
	//
	// Description:
	//	CONACloseFS closes the given file system connection.
	//
	// Parameters:
	//	hFSHandle	[in] Existing file system handle
	//
	// Return values:
	//	CONA_OK
	//	ECONA_INVALID_HANDLE
	//	ECONA_NOT_INITIALIZED
	//	ECONA_UNKNOWN_ERROR
	//
		PCCS_FSAPI CONACloseFS( FSHANDLE hFSHandle );
	//=========================================================

	//=========================================================
	// CONARegisterFSNotifyCallback
	//
	// Description:
	// CONARegisterFSNotifyCallback registers or unregisters the 
	// callback function for the file functions' status notifications.
	// 
	// During file operations, the Connectivity API calls this function 
	// with the parameter's state (0-100%), connection handle, and 
	// operation code.
	//
	// Connectivity API 2.0 (or newer), callback function's state parameter can get 
	// CONA_WAIT_CONNECTION_IS_BUSY value. This means that operation started ok 
	// but other application is reserved connection, please wait.
	// NOTE: This feature used only when Connectivity API is initialized by value 20 or bigger.
	//
	//
	// Parameters:
	//	hFSHandle	[in] File System handle
	//	dwState		[in] Register flag:
	//					  API_REGISTER:   Registers a callback function
	//					  API_UNREGISTER: Unregisters a callback function
	//	pFSNotify	[in] Pointer to a function.
	//
	// Return values:
	//	CONA_OK
	//	ECONA_INVALID_HANDLE
	//	ECONA_INVALID_POINTER
	//	ECONA_INVALID_PARAMETER
	//	ECONA_NOT_INITIALIZED
	//	ECONA_REGISTER_ALREADY_DONE
	//	ECONA_UNKNOWN_ERROR
	//
		PCCS_FSAPI CONARegisterFSNotifyCallback( FSHANDLE hFSHandle,
											   DWORD	 dwState,
											   PFN_CONA_FS_CALLBACK pFSNotify );
	//=========================================================

	//=========================================================
	// CONARegisterFSNotifyIF
	//
	// Description:
	//	CONARegisterFSNotifyIF is used to register or unregister 
	//	a notification interface for the FSAPI API notifications.
	//
	// Parameters:
	//	hFSHandle		[in] File system handle
	//	dwState			[in] Used to define the action:
	//						 API_REGISTER used in registeration
	//						 API_UNREGISTER used in removing the registeration
	//	pINotify		[in] Pointer to IFSAPINotify implementation
	//
	// Return values:
	// CONA_OK
	// ECONA_INVALID_POINTER
	// ECONA_INVALID_PARAMETER
	// ECONA_INVALID_HANDLE
	// ECONA_NOT_INITIALIZED
	// ECONA_UNKNOWN_ERROR
	//
	#ifdef __cplusplus
		PCCS_FSAPI CONARegisterFSNotifyIF(
								FSHANDLE hFSHandle, 
								DWORD dwState, 
								IFSAPINotify* pINotify );
	#endif
	//=========================================================

	//=========================================================
	// CONARefreshDeviceMemoryValues
	//
	// Description:
	//	CONARefreshDeviceMemoryValues refreshes the memory values 
	// from the device. The function caches the memory values, so 
	// it must be called if it is required to get the latest information.
	//
	// Parameters:
	//	hFSHandle	[in] File system handle
	//
	// Return values:
	//	CONA_OK
	//	ECONA_INVALID_HANDLE
	//	ECONA_CONNECTION_BUSY
	//	ECONA_CONNECTION_LOST
	//	ECONA_INVALID_DATA_DEVICE
	//	ECONA_CANCELLED
	//	ECONA_FAILED_TIMEOUT
	//	ECONA_UNKNOWN_ERROR_DEVICE
	//	ECONA_NOT_INITIALIZED
	//	ECONA_UNKNOWN_ERROR
	//
		PCCS_FSAPI CONARefreshDeviceMemoryValues( FSHANDLE hFSHandle );
	//=========================================================

	//=========================================================
	// CONAGetMemoryTypes
	//
	// Description:
	// CONAGetMemoryTypes receives all memory types that currently 
	// exist in the device. The format of its string is 
	// "Memory type string" comma "next Memory type string". An 
	// example of a string is "DEV,MMC,APPL". 
	// 
	// The device can include different memory types. For example, 
	// the memory types can be "DEV" (device memory), "MMC" 
	// (memory card), or "APPL" (device special memory).	
	//
	// Parameters:
	//	hFSHandle			[in]  File system handle.
	//	ppstrMemoryTypes	[out] Memory types.
	//
	// Return values:
	//	CONA_OK
	//	ECONA_INVALID_HANDLE
	//	ECONA_INVALID_POINTER
	//	ECONA_NOT_SUPPORTED_DEVICE
	//	ECONA_NOT_INITIALIZED
	//	ECONA_UNKNOWN_ERROR
	//
		PCCS_FSAPI CONAGetMemoryTypes( FSHANDLE hFSHandle, WCHAR** ppstrMemoryTypes );
	//=========================================================
	
	//=========================================================
	// CONAGetMemoryValues
	//
	// Description:
	//	CONAGetDeviceMemory returns info about the given device memory type.
	//
	// Parameters:
	//	hFSHandle		[in]  File System handle.
	//	pstrMemoryType	[in]  Inquired device memory.E.g. "DEV", "MMC", 
	//                        or "APPL".If the value is NULL, the used value is "DEV".
	//	pdlFree			[out] Pointer to the variable receiving the 
	//						  information on the amount of free memory.
	//						  If not available, the value is -1.
	//	pdlTotal		[out] Pointer to the variable receiving 
	//						  the information on the total memory.
	//						  If not available, the value is -1.
	//	pdlUsed			[out] Pointer to the variable receiving 
	//						  the information on the used memory.
	//						  If not available, the value is -1.
	//
	// Return values:
	//	CONA_OK
	//	ECONA_INVALID_HANDLE
	//	ECONA_INVALID_POINTER
	//	ECONA_INVALID_PARAMETER
	//	ECONA_NOT_SUPPORTED_DEVICE
	//	ECONA_NOT_INITIALIZED
	//	ECONA_UNKNOWN_ERROR
	//
		PCCS_FSAPI CONAGetMemoryValues( FSHANDLE hFSHandle,
									  const WCHAR*	pstrMemoryType,
									  __int64* pdlFree, 
									  __int64* pdlTotal,
									  __int64* pdlUsed );
	//=========================================================

	//=========================================================
	// CONASetCurrentFolder
	//
	// Description:
	// CONASetCurrentFolder sets the device's current folder. All 
	// file and folder operations with a relative path reference 
	// will use this value. After the connection is established, 
	// the default value is the device's root-folder. Only backslashes 
	// ("\") are permissible folder separators.
	// 
	// Any other FS operation does not change the current folder. 
	// If CONASetCurrentFolder fails, the currect folder is not changed. 
	//
	// Parameters:
	//	hFSHandle	[in] File System handle
	//	pstrPath	[in] Name of the new current folder. Its value may 
	//					 be a relative or absolute reference. If the 
	//					 absolute path is used, the first two characters 
	//					 must be backslashes "\\". If you set the current 
	//					 folder to the root-folder, the path must include