Author: hpoussin Date: Fri Jul 25 15:27:05 2008 New Revision: 34792
URL: http://svn.reactos.org/svn/reactos?rev=34792&view=rev Log: Add comments Better interface declarations
Modified: trunk/reactos/lib/recyclebin/recyclebin.h
Modified: trunk/reactos/lib/recyclebin/recyclebin.h URL: http://svn.reactos.org/svn/reactos/trunk/reactos/lib/recyclebin/recyclebin.h... ============================================================================== --- trunk/reactos/lib/recyclebin/recyclebin.h [iso-8859-1] (original) +++ trunk/reactos/lib/recyclebin/recyclebin.h [iso-8859-1] Fri Jul 25 15:27:05 2008 @@ -6,7 +6,10 @@ #endif
#include <windows.h> +#include <objbase.h> #define ANY_SIZE 1 + +/* Structures used by the API Interface */
typedef struct _DELETED_FILE_DETAILS_A { @@ -34,12 +37,29 @@ #define PDELETED_FILE_DETAILS PDELETED_FILE_DETAILS_A #endif
+/* API Interface */ + +/* Function called for each deleted file in the recycle bin + * Context: value given by the caller of the EnumerateRecycleBin function + * hDeletedFile: a handle to the deleted file + * Returning FALSE stops the enumeration. + * Remarks: the handle must be closed with the CloseRecycleBinHandle function + */ typedef BOOL (WINAPI *PENUMERATE_RECYCLEBIN_CALLBACK)(IN PVOID Context, IN HANDLE hDeletedFile);
+/* Closes a file deleted handle. + * hDeletedFile: the handle to close + * Returns TRUE if operation succeeded, FALSE otherwise. + * Remark: The handle is obtained in the PENUMERATE_RECYCLEBIN_CALLBACK callback + */ BOOL WINAPI CloseRecycleBinHandle( IN HANDLE hDeletedFile);
+/* Moves a file to the recycle bin. + * FileName: the name of the file to move the recycle bin + * Returns TRUE if operation succeeded, FALSE otherwise. + */ BOOL WINAPI DeleteFileToRecycleBinA( IN LPCSTR FileName); @@ -52,6 +72,11 @@ #define DeleteFileToRecycleBin DeleteFileToRecycleBinA #endif
+/* Removes all elements contained in a recycle bin + * pszRoot: the name of the drive containing the recycle bin + * Returns TRUE if operation succeeded, FALSE otherwise. + * Remarks: 'pszRoot' can be NULL to mean 'all recycle bins'. + */ BOOL WINAPI EmptyRecycleBinA( IN LPCSTR pszRoot OPTIONAL); @@ -64,6 +89,13 @@ #define EmptyRecycleBin EmptyRecycleBinA #endif
+/* Enumerate contents of a recycle bin. + * pszRoot: the name of the drive containing the recycle bin + * pFnCallback: callback function to be called for each deleted item found + * Context: some value which will be given back in the callback function + * Returns TRUE if operation succeeded, FALSE otherwise. + * Remarks: 'pszRoot' can be NULL to mean 'all recycle bins'. + */ BOOL WINAPI EnumerateRecycleBinA( IN LPCSTR pszRoot OPTIONAL, @@ -80,6 +112,14 @@ #define EnumerateRecycleBin EnumerateRecycleBinA #endif
+/* Gets details about a deleted file + * hDeletedFile: handle of the deleted file to get details about + * BufferSize: size of the 'FileDetails' buffer, in bytes + * FileDetails: if the function succeeded, contains details about the deleted file + * RequiredSize: contains the minimal buffer size required to get file information details + * Returns TRUE if operation succeeded, FALSE otherwise. + * Remark: The handle is obtained in the PENUMERATE_RECYCLEBIN_CALLBACK callback + */ BOOL WINAPI GetDeletedFileDetailsA( IN HANDLE hDeletedFile, @@ -98,67 +138,87 @@ #define GetDeletedFileDetails GetDeletedFileDetailsA #endif
+/* Restores a deleted file + * hDeletedFile: handle of the deleted file to restore + * Returns TRUE if operation succeeded, FALSE otherwise. + * Remarks: if the function succeeds, the handle is not valid anymore. + */ BOOL WINAPI RestoreFile( IN HANDLE hDeletedFile);
/* COM interface */
-typedef interface IRecycleBinFile IRecycleBinFile; +#undef INTERFACE +#define INTERFACE IRecycleBinFile + +DECLARE_INTERFACE_(IRecycleBinFile, IUnknown) +{ + BEGIN_INTERFACE + + /* IUnknown methods */ + STDMETHOD(QueryInterface)(THIS_ REFIID riid, void **ppvObject) PURE; + STDMETHOD_(ULONG, AddRef)(THIS) PURE; + STDMETHOD_(ULONG, Release)(THIS) PURE; + + /* IRecycleBinFile methods */ + STDMETHOD(GetLastModificationTime)(THIS_ FILETIME *pLastModificationTime) PURE; + STDMETHOD(GetDeletionTime)(THIS_ FILETIME *pDeletionTime) PURE; + STDMETHOD(GetFileSize)(THIS_ ULARGE_INTEGER *pFileSize) PURE; + STDMETHOD(GetPhysicalFileSize)(THIS_ ULARGE_INTEGER *pPhysicalFileSize) PURE; + STDMETHOD(GetAttributes)(THIS_ DWORD *pAttributes) PURE; + STDMETHOD(GetFileName)(THIS_ SIZE_T BufferSize, LPWSTR Buffer, SIZE_T *RequiredSize) PURE; + STDMETHOD(Delete)(THIS) PURE; + STDMETHOD(Restore)(THIS) PURE; + + END_INTERFACE +}; + +#undef INTERFACE +#define INTERFACE IRecycleBinEnumList + +DECLARE_INTERFACE_(IRecycleBinEnumList, IUnknown) +{ + BEGIN_INTERFACE + + /* IUnknown methods */ + STDMETHOD(QueryInterface)(THIS_ REFIID riid, void **ppvObject) PURE; + STDMETHOD_(ULONG, AddRef)(THIS) PURE; + STDMETHOD_(ULONG, Release)(THIS) PURE; + + /* IRecycleBinEnumList methods */ + STDMETHOD(Next)(THIS_ DWORD celt, IRecycleBinFile **rgelt, DWORD *pceltFetched); + STDMETHOD(Skip)(THIS_ DWORD celt) PURE; + STDMETHOD(Reset)(THIS) PURE; + + END_INTERFACE +}; + +#undef INTERFACE +#define INTERFACE IRecycleBin + +DECLARE_INTERFACE_(IRecycleBin, IUnknown) +{ + BEGIN_INTERFACE + + /* IUnknown methods */ + STDMETHOD(QueryInterface)(THIS_ REFIID riid, void **ppvObject) PURE; + STDMETHOD_(ULONG, AddRef)(THIS) PURE; + STDMETHOD_(ULONG, Release)(THIS) PURE; + + /* IRecycleBin methods */ + STDMETHOD(DeleteFile)(THIS_ LPCWSTR szFileName); + STDMETHOD(EmptyRecycleBin)(THIS); + STDMETHOD(EnumObjects)(THIS_ IRecycleBinEnumList **ppEnumList); + + END_INTERFACE +}; + EXTERN_C const IID IID_IRecycleBinFile; - -typedef struct IRecycleBinFileVtbl -{ - HRESULT (STDMETHODCALLTYPE *QueryInterface)( - IN IRecycleBinFile *This, - IN REFIID riid, - OUT void **ppvObject); - - ULONG (STDMETHODCALLTYPE *AddRef)( - IN IRecycleBinFile *This); - - ULONG (STDMETHODCALLTYPE *Release)( - IN IRecycleBinFile *This); - - HRESULT (STDMETHODCALLTYPE *GetLastModificationTime)( - IN IRecycleBinFile *This, - OUT FILETIME *pLastModificationTime); - - HRESULT (STDMETHODCALLTYPE *GetDeletionTime)( - IN IRecycleBinFile *This, - OUT FILETIME *pDeletionTime); - - HRESULT (STDMETHODCALLTYPE *GetFileSize)( - IN IRecycleBinFile *This, - OUT ULARGE_INTEGER *pFileSize); - - HRESULT (STDMETHODCALLTYPE *GetPhysicalFileSize)( - IN IRecycleBinFile *This, - OUT ULARGE_INTEGER *pPhysicalFileSize); - - HRESULT (STDMETHODCALLTYPE *GetAttributes)( - IN IRecycleBinFile *This, - OUT DWORD *pAttributes); - - HRESULT (STDMETHODCALLTYPE *GetFileName)( - IN IRecycleBinFile *This, - IN SIZE_T BufferSize, - IN OUT LPWSTR Buffer, - OUT SIZE_T *RequiredSize); - - HRESULT (STDMETHODCALLTYPE *Delete)( - IN IRecycleBinFile *This); - - HRESULT (STDMETHODCALLTYPE *Restore)( - IN IRecycleBinFile *This); -} IRecycleBinFileVtbl; - -interface IRecycleBinFile -{ - CONST_VTBL struct IRecycleBinFileVtbl *lpVtbl; -}; - -#ifdef COBJMACROS +EXTERN_C const IID IID_IRecycleBinEnumList; +EXTERN_C const IID IID_IRecycleBin; + +#if (!defined(__cplusplus) || defined(CINTERFACE)) && defined(COBJMACROS) #define IRecycleBinFile_QueryInterface(This, riid, ppvObject) \ (This)->lpVtbl->QueryInterface(This, riid, ppvObject) #define IRecycleBinFile_AddRef(This) \ @@ -181,44 +241,7 @@ (This)->lpVtbl->Delete(This) #define IRecycleBinFile_Restore(This) \ (This)->lpVtbl->Restore(This) -#endif - -typedef interface IRecycleBinEnumList IRecycleBinEnumList; -EXTERN_C const IID IID_IRecycleBinEnumList; - -typedef struct IRecycleBinEnumListVtbl -{ - HRESULT (STDMETHODCALLTYPE *QueryInterface)( - IN IRecycleBinEnumList *This, - IN REFIID riid, - OUT void **ppvObject); - - ULONG (STDMETHODCALLTYPE *AddRef)( - IN IRecycleBinEnumList *This); - - ULONG (STDMETHODCALLTYPE *Release)( - IN IRecycleBinEnumList *This); - - HRESULT (STDMETHODCALLTYPE *Next)( - IN IRecycleBinEnumList *This, - IN DWORD celt, - IN OUT IRecycleBinFile **rgelt, - OUT DWORD *pceltFetched); - - HRESULT (STDMETHODCALLTYPE *Skip)( - IN IRecycleBinEnumList *This, - IN DWORD celt); - - HRESULT (STDMETHODCALLTYPE *Reset)( - IN IRecycleBinEnumList *This); -} IRecycleBinEnumListVtbl; - -interface IRecycleBinEnumList -{ - CONST_VTBL struct IRecycleBinEnumListVtbl *lpVtbl; -}; - -#ifdef COBJMACROS + #define IRecycleBinEnumList_QueryInterface(This, riid, ppvObject) \ (This)->lpVtbl->QueryInterface(This, riid, ppvObject) #define IRecycleBinEnumList_AddRef(This) \ @@ -231,42 +254,7 @@ (This)->lpVtbl->Skip(This, celt) #define IRecycleBinEnumList_Reset(This) \ (This)->lpVtbl->Reset(This) -#endif - -typedef interface IRecycleBin IRecycleBin; -EXTERN_C const IID IID_IRecycleBin; - -typedef struct IRecycleBinVtbl -{ - HRESULT (STDMETHODCALLTYPE *QueryInterface)( - IN IRecycleBin *This, - IN REFIID riid, - OUT void **ppvObject); - - ULONG (STDMETHODCALLTYPE *AddRef)( - IN IRecycleBin *This); - - ULONG (STDMETHODCALLTYPE *Release)( - IN IRecycleBin *This); - - HRESULT (STDMETHODCALLTYPE *DeleteFile)( - IN IRecycleBin *This, - IN LPCWSTR szFileName); - - HRESULT (STDMETHODCALLTYPE *EmptyRecycleBin)( - IN IRecycleBin *This); - - HRESULT (STDMETHODCALLTYPE *EnumObjects)( - IN IRecycleBin *This, - OUT IRecycleBinEnumList **ppEnumList); -} IRecycleBinVtbl; - -interface IRecycleBin -{ - CONST_VTBL struct IRecycleBinVtbl *lpVtbl; -}; - -#ifdef COBJMACROS + #define IRecycleBin_QueryInterface(This, riid, ppvObject) \ (This)->lpVtbl->QueryInterface(This, riid, ppvObject) #define IRecycleBin_AddRef(This) \