conadevicemanagement.h

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

/*
==============================================================================
* Device Management API 3.2
*
Filename    : CONADeviceManagement.h
Description : Device Management 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 _CONADEVICEMANAGEMENT_H_
#define _CONADEVICEMANAGEMENT_H_

///////////////////////////////////////////////////////////
// PC Connectivity API
///////////////////////////////////////////////////////////
	#ifndef PCCS_DMAPI
		#define PCCS_DMAPI DWORD STDAPICALLTYPE
	#endif
///////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////
// Device Management API definitions
///////////////////////////////////////////////////////////
	#include "DMAPIDefinitions.h"
///////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////
// Device Management API
///////////////////////////////////////////////////////////

	//=========================================================
	// Device Management API versions 
	//
		#define DMAPI_VERSION_30		30
		#define DMAPI_VERSION_31		31
		#define DMAPI_VERSION_32		32
	//=========================================================

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

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

	//=========================================================
	// DMAPI_GetAPIVersion
	//
	// Description:
	//	Returns currently installed version of this DMAPI. 	
	//
	// Parameters:
	//
	// Return values:
	//	API version number. 
	//
		PCCS_DMAPI DMAPI_GetAPIVersion();
	//=========================================================

	//=========================================================
	// CONAOpenDM
	//
	// Description:
	//	CONAOpenDM opens the device management connection. 
	//	It returns a handle to the device management context.
	//	This must be used in all device management functions.
	//
	// Parameters:
	//	phDMHandle		[out] Device manager handle
	//
	// Return values:
	// CONA_OK
	// ECONA_INVALID_POINTER
	// ECONA_NOT_INITIALIZED
	// ECONA_NOT_ENOUGH_MEMORY
	// ECONA_INIT_FAILED_COM_INTERFACE
	// ECONA_UNKNOWN_ERROR
	// 
		PCCS_DMAPI CONAOpenDM(DMHANDLE* phDMHandle);
	//=========================================================

	//=========================================================
	// CONACloseDM
	//
	// Description:
	//	CONACloseDM is used to close device management connection. 
	//	This must be called for each device management handle 
	//	when it is not needed anymore.
	//
	// Parameters:
	//	hDMHandle		[in] Device manager handle
	//
	// Return values:
	// CONA_OK
	// ECONA_INVALID_HANDLE
	// ECONA_NOT_INITIALIZED
	// ECONA_UNKNOWN_ERROR
	// 
		PCCS_DMAPI CONACloseDM(DMHANDLE hDMHandle);
	//=========================================================

	//=========================================================
	// CONASetDeviceListOption
	//
	// Description:
	//	CONASetDeviceListOption is used to set different options for DMAPI.
	//	Currently only DMAPI_OPTION_SET_MANUFACTURER option is supported. It
	//	can be used to set manufacturer info for the DMAPI. This information 
	//	is used when filtering showed devices. If this option is not is not
	//	set, all connected devices are added to the device list.
	//	This function can be called multiple times with different manufacturer 
	//	names to support devices from multiple manufacturers.
	//	Once called with pstrValue set as NULL clears the filtering.
	//
	// Parameters:
	//	hDMHandle			[in] Device manager handle
	//	dwOptions			[in] Options. Currently only DMAPI_OPTION_SET_MANUFACTURER is supported.
	//	pstrValue			[in] String buffer containing the name of the manufacturer.
	//							 If NULL, filtering is disables.
	//
	// Return values:
	// CONA_OK
	// ECONA_INVALID_POINTER
	// ECONA_NOT_INITIALIZED
	// ECONA_UNKNOWN_ERROR
	// 
		PCCS_DMAPI CONASetDeviceListOption(DMHANDLE hDMHandle, DWORD dwOptions, const WCHAR* pstrValue);
	//=========================================================

	//=========================================================
	// CONAGetDeviceCount
	//
	// Description:
	//	CONAGetDeviceCount puts the count of devices into the 
	//	given DWORD. 
	//
	// Parameters:
	//	hDMHandle		[in]  Device manager handle
	//	pdwCount		[out] Pointer to the variable receiving 
	//						  the count of devices.
	//
	// Return values:
	// CONA_OK
	// ECONA_INVALID_POINTER
	// ECONA_INVALID_HANDLE
	// ECONA_NOT_INITIALIZED
	// ECONA_UNKNOWN_ERROR
	// 
		PCCS_DMAPI CONAGetDeviceCount(DMHANDLE hDMHandle, DWORD* pdwCount);
	//=========================================================

	//=========================================================
	// CONAGetDevices
	//
	// Description:
	//	CONAGetDevices allocates and sets devices information to 
	//	allocate the CONAPI_DEVICE structs and returns the count 
	//	of the used CONAPI_DEVICE structs.  The allocated memory 
	//	MUST be freed by calling the CONAFreeDeviceStructure function. 
	//	
	//	Every CONAPI_DEVICE struct includes CONAPI_CONNECTION_INFO 
	//	sturct(s), which include the media type information. 
	//	If the device is connected via different medias at the 
	//	same time, there is an individual CONAPI_CONNECTION_INFO for 
	//	each media type.

	//
	// Parameters:
	//  hDMHandle		[in]  Device manager handle
	//  pdwCount		[in,out] In: Number of allocated CONAPI_DEVICE structs.
	//							 Out: Number of used CONAPI_DEVICE structs.
	//  pDevices		[out] Pointer to receiving CONAPI_DEVICE structures.
	//
	// Return values:
	// CONA_OK
	// ECONA_INVALID_POINTER
	// ECONA_INVALID_PARAMETER
	// ECONA_INVALID_HANDLE
	// ECONA_NOT_INITIALIZED
	// ECONA_UNKNOWN_ERROR
	//
		PCCS_DMAPI CONAGetDevices(
							DMHANDLE hDMHandle, 
							DWORD* pdwCount, 
							CONAPI_DEVICE* pDevices );
	//=========================================================

	//=========================================================
	// CONAGetDevice
	//
	// Description:
	//	CONAGetDevice function allocates and sets the device's 
	//	information to the allocated CONAPI_DEVICE struct.
	//
	// Parameters:
	//	hDMHandle			[in]  Device manager handle
	//  pstrSerialNumber	[in]  Device's serial number.
	//  pDevice				[out] Pointer to device struct
	// 
	// Return values:
	// CONA_OK
	// ECONA_INVALID_POINTER
	// ECONA_INVALID_HANDLE
	// ECONA_DEVICE_NOT_FOUND
	// ECONA_NOT_INITIALIZED
	// ECONA_UNKNOWN_ERROR
	//
		PCCS_DMAPI CONAGetDevice(
							DMHANDLE hDMHandle, 
							const WCHAR* pstrSerialNumber, 
							CONAPI_DEVICE* pDevice );
	//=========================================================

	//=========================================================
	// CONAFreeDeviceStructure
	//
	// Description:
	//	CONAFreeDeviceStructure releases the memory, which 
	//	ConnectivityAPI is allocated inside the CONAPI_DEVICE structs.
	//
	// Parameters:
	//	dwCount			[in] Number of the used CONAPI_DEVICE structs. 
	//		The same number value if CONAGetDevices function is used. 
	//		The value must be the number of the used structs (pdwCount). 
	//		If the CONAGetDevice function is used, the value must be 1.
	//	pDevices		[in] Pointer to the device's struct list.
	//
	// Return values:
	//	CONA_OK
	//	ECONA_INVALID_POINTER
	//	ECONA_INVALID_PARAMETER
	//	ECONA_UNKNOWN_ERROR
	//
		PCCS_DMAPI CONAFreeDeviceStructure( DWORD dwCount, CONAPI_DEVICE* pDevices );
	//=========================================================

	//=========================================================
	// CONARefreshDeviceList
	//
	// Description:
	//	CONARefreshDeviceList function starts to refresh the 
	//	Device list. All changes will be notified via notifications.
	//
	// Parameters:
	//	hDMHandle		[in] Device manager handle
	//	dwValue			[in] Reserved for future use. Must be zero.
	//
	// Return values:
	// CONA_OK
	// ECONA_INVALID_PARAMETER
	// ECONA_INVALID_HANDLE
	// ECONA_NOT_INITIALIZED
	// ECONA_UNKNOWN_ERROR
	//
		PCCS_DMAPI CONARefreshDeviceList(DMHANDLE hDMHandle, DWORD dwValue );
	//=========================================================

	//=========================================================
	// CONARenameFriendlyName
	//
	// Description:
	//	Renames the device's friendly name. Current device's 
	//	friendly name string is in the CONAPI_DEVICE struct;