'Filename    : CONAFileSystem.vb
'Part of     : Connectivity API VB.NET examples
'Description : Connectivity API data definitions, converted from CONAFileSystem.h
'Version     : 3.2
'
'This example is only to be used with PC Connectivity API version 3.2.
'Compability ("as is") with future versions is not quaranteed.
'
'Copyright (c) 2007 Nokia Corporation.
'
'This material, including but not limited to documentation and any related
'computer programs, is protected by intellectual property rights of Nokia
'Corporation and/or its licensors.
'All rights are reserved. Reproducing, modifying, translating, or
'distributing any or all of this material requires the prior written consent
'of Nokia Corporation. Nokia Corporation retains the right to make changes
'to this material at any time without notice. A copyright license is hereby
'granted to download and print a copy of this material for personal use only.
'No other license to any other intellectual property rights is granted. The
'material 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.

Option Strict Off
Option Explicit On 

Imports System.Runtime.InteropServices

Module CONAFileSystem
    '=========================================================
    ' File System API versions 
    '
    Public Const FSAPI_VERSION_30 As Short = 30
    Public Const FSAPI_VERSION_31 As Short = 31
    Public Const FSAPI_VERSION_32 As Short = 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:
    '
    Public Declare Function FSAPI_Initialize Lib "ConnAPI" (ByVal iAPIVersion As Integer, ByVal pdwParam As IntPtr) As Integer

    '=========================================================
    '
    '=========================================================
    ' 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:
    '
    Public Declare Function FSAPI_Terminate Lib "ConnAPI" (ByVal pdwParam As IntPtr) As Integer

    '=========================================================
    '
    '=========================================================
    ' FSAPI_GetAPIVersion
    '
    ' Description:
    '	Returns currently installed version of this FSAPI.
    '
    ' Parameters:
    '
    ' Return values:
    '	API version number. 
    '
    Public Declare Function FSAPI_GetAPIVersion Lib "ConnAPI" () As Integer


    '///////////////////////////////////////////////////////////
    ' ConnectivityAPI File System functions
    '///////////////////////////////////////////////////////////

    '=========================================================
    ' 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 API_MEDIA_ALL, the ServiceLayer 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 ServiceLayer tries to open the FS connection in the 
    '	following order: USB, Seria, 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 piDeviceID parameter. The 
    '	piMedia parameter is not used in the exemplary case.
    '
    ' Parameters:
    '	pstrSerialNumber [in]     The device's serial number, which must be set.
    '	piMedia		     [in,out] In: Media type, which defines the target
    '					          media for the Device's FS connection.
    '							  Out:If the value is API_MEDIA_ALL, the 
    '							  target media is selected automatically 
    '							  and the used media type is returned.
    '	phFSHandle		 [out]	  Handle to the opened FS connection
    '	piDeviceID		 [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
    '
    Public Declare Function CONAOpenFS Lib "ConnAPI" (<MarshalAs(UnmanagedType.LPWStr)> ByVal pstrSerialNumber As String, ByRef piMedia As Integer, ByRef phFSHandle As Integer, ByRef piDeviceID As Integer) As Integer
    '=========================================================

    '=========================================================
    ' 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
    '
    Public Declare Function CONACloseFS Lib "ConnAPI" (ByVal hFSHandle As Integer) As Integer
    '=========================================================

    '=========================================================
    ' CONARegisterFSNotifyCallback
    '
    ' Description:
    ' CONARegisterFSNotifyCallback registers or unregisters the 
    ' callback function for the file functions' status notifications.
    ' 
    ' During file operations, the connectionAPI calls this function 
    ' with the parameter's state (0-100%), connection handle, and 
    ' operation code.

    '
    ' Parameters:
    '	hFSHandle	[in] File System handle
    '	iState		[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_UNKNOWN_ERROR
    '
    Public Declare Function CONARegisterFSNotifyCallback Lib "ConnAPI" (ByVal hFSHandle As Integer, ByVal iState As Integer, ByVal pFSNotify As FSNotifyCallbackDelegate) As Integer
    '=========================================================

    '=========================================================
    ' 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
    '
    Public Declare Function CONARefreshDeviceMemoryValues Lib "ConnAPI" (ByVal hFSHandle As Integer) As Integer
    '=========================================================

    '=========================================================
    ' 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
    '
    Public Declare Function CONAGetMemoryTypes Lib "ConnAPI" (ByVal hFSHandle As Integer, <MarshalAs(UnmanagedType.LPWStr)> ByRef ppstrMemoryTypes As String) As Integer
    '=========================================================

    '=========================================================
    ' 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
    '
    Public Declare Function CONAGetMemoryValues Lib "ConnAPI" (ByVal hFSHandle As Integer, <MarshalAs(UnmanagedType.LPWStr)> ByVal pstrMemoryType As String, ByRef pdlFree As Int64, ByRef pdlTotal As Int64, ByRef pdlUsed As Int64) As Integer
    '=========================================================

    '=========================================================
    ' 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 
    '					 only two backslash characters "\\".
    '					 If the current folder is required to move sub folder, 
    '					 the path must not include any backslashes.
    '					 If the current folder is required to change the 
    '					 parent folder, the first two characters must be dots
    '					 and the third character must be a backslash "..\". 
    '
    ' Return values:
    '	CONA_OK
    '	ECONA_INVALID_HANDLE
    '	ECONA_INVALID_PARAMETER
    '	ECONA_CONNECTION_BUSY
    '	ECONA_CONNECTION_LOST
    '	ECONA_CURRENT_FOLDER_NOT_FOUND
    '	ECONA_FOLDER_PATH_TOO_LONG
    '	ECONA_FOLDER_NAME_INVALID_DEVICE
    '	ECONA_FOLDER_NO_PERMISSION