;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; ;; Copyright (C) KolibriOS team 2011-2012. All rights reserved. ;; ;; Distributed under terms of the GNU General Public License ;; ;; ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; All functions are stdcall unless mentioned otherwise. === Disk === The kernel exports the functions 'DiskAdd', 'DiskMediaChanged', 'DiskDel' for drivers. They must be called in the following order: DiskAdd, then zero or more DiskMediaChanged, then optionally DiskDel. The driver must not call two functions in parallel, including two calls to DiskMediaChanged. void* DiskAdd(DISKFUNC* functions, const char* name, void* userdata, int flags); ; The pointer 'functions' must be valid at least until the disk will be deleted ; (until DISKFUNC.close is called). ; The pointer 'name' can be invalid after this function returns. ; It should point to ASCIIZ-string without leading '/' in latin lowercase and ; digits, like 'usbhd0'. ; The value 'userdata' is any pointer-sized data, passed as is to all ; callbacks. DISK_NO_INSERT_NOTIFICATION = 1 ; The bitfield 'flags' has currently only one bit defined. If it is set, the ; driver will never call DiskMediaChanged(hDisk, true), so the kernel must scan ; for media insertion when the operation is requested. struc DISKFUNC { .strucsize dd ? .close dd ? ; void close(void* userdata); ; Optional. ; The last function that is called for the given disk. The kernel calls it when ; the kernel has finished all operations with the disk and it is safe to free ; all driver-specific data identified by 'userdata'. .closemedia dd ? ; void closemedia(void* userdata); ; Optional. ; The kernel calls this function when it finished all processing with the ; current media. If media is removed, the driver should decline all requests ; to that media with DISK_STATUS_NO_MEDIA, even if new media is inserted, ; until this function is called. If media is removed, a new call to ; DiskMediaChanged(hDisk, true) is not allowed until this function is called. .querymedia dd ? ; int querymedia(void* userdata, DISKMEDIAINFO* info); ; return value: 0 = success, otherwise = error .read dd ? ; int read(void* userdata, void* buffer, __int64 startsector, ; int* numsectors); ; return value: 0 = success, otherwise = error .write dd ? ; int write(void* userdata, const void* buffer, __int64 startsector, ; int* numsectors); ; Optional. ; return value: 0 = success, otherwise = error .flush dd ? ; int flush(void* userdata); ; Optional. ; Flushes the hardware cache, if it exists. Note that a driver should not ; implement a software cache for read/write, since they are called from the ; kernel cache manager. .adjust_cache_size dd ? ; unsigned int adjust_cache_size(unsigned int suggested_size); ; Optional. ; Returns the cache size for this device in bytes. 0 = disable cache. } struc DISKMEDIAINFO { .flags dd ? DISK_MEDIA_READONLY = 1 .sectorsize dd ? .capacity dq ? } void DiskDel(void* hDisk); ; This function informs the kernel that the disk should be deleted from the ; system. This function removes the disk from the global file system; however, ; it is possible that active operations with the disk are still running. When ; the disk is actually removed, the kernel calls the 'close' function, which ; can free all device-related resources. void DiskMediaChanged(void* hDisk, int newstate); ; This function informs the kernel that a media has been inserted, removed or ; changed. 'newstate' should be zero if currently there is no media inserted ; and nonzero in the other case. This function must not be called with nonzero ; 'newstate' from any of callbacks. This function must not be called if another ; call to this function is active. === Timers === Timers allow to schedule a function call to some time in the future, once or periodically. A timer function can do anything, including adding/removing other timers and itself, but it should not run time-consuming tasks, since that would block the processing thread for a long time; for such tasks it is recommended to create new thread. void* TimerHS(unsigned int deltaStart, unsigned int interval, void* timerFunc, void* userData); ; Registers a timer which is activated in (deltaStart == 0 ? deltaStart : ; interval) 1/100ths of second starting from the current time. If interval ; is zero, this timer is automatically deleted when activated. Otherwise, ; this timer will be activated every (interval) 1/100ths of second from the ; first activation. Activated timer calls timerFunc(userData) as stdcall. ; Returned value: NULL = failed, otherwise = timer handle which can be passed ; to CancelTimerHS. void CancelTimerHS(void* hTimer); ; Cancels previously registered timer.