api3.docx

api3.docx

《api3.docx》由会员分享，可在线阅读，更多相关《api3.docx（11页珍藏版）》请在冰豆网上搜索。

api3

快速文件系统

实习内容：

见课本P433-434。

要用到的API函数如下：

一、CREATEFILE函数

简介：

这是程序中使用次数最多的函数，其主要功能是获得我们在第一个参数中指定的文件的句柄，该文件可以是已经存在的文件，这时可以将函数的第四个参数设定为OPEN_EXISTING来保证我们得到的是已经存在的文件的句柄，如果将参数设定为OPEN_ALWAYS，那么如果文件不存在，函数会新建一个命名为第一个参数的文件。

函数的其它参数可以设定打开的文件的属性和安全性，这些属性和本程序的关系不大，这里不加叙述。

函数的第三个参数决定了我们对文件采用的传输方式对于普通的传输模式我们将参数值设为FILE_ATTRIBUTE_NORMAL，而采用FILE_FLAG_NO_BUFFERING模式表示不使用高速缓存文件传输，同时使用标志FILE_FLAG_NO_BUFFERING和FILE_FLAG_OVERLAPPED可以充分发挥异步传输模式的功能，而FILE_FLAG_SEQUENTIAL_SCAN表示我们使用高速缓存模式进行文件传输。

程序中我们分别使用上面提到的三种参数值生成文件句柄，进行后续的文件操作。

函数功能：

该函数用来创建或打开下列对象并返回一个用于读取该对象的句柄：

Files：

文件；Pipes：

管道；Mailslots：

邮件插口；Communicationsresources：

通讯资源；Directions：

目录；Diskdevices（WindowsNTonly）：

磁盘设备（只用于WindowsNT）；Consoles：

控制台。

函数原型：

HANDLECreateFile（LPCTSTRlpFileName，

DWORDdwDesiredAccess，DWORDdwShareMode，

LPSECURITY_ATTRIBUTESlpSecurityAttributes，DWORDdwCreationDisposition，

DWORDdwFlagsAndAttributes,HANDLEhTemplateFile）；

参数：

lpFileName：

指向一个以NULL结束的字符串的指针，该字符串用于创建或打开对象、指定对象名。

如果lpFileName参数值是一个路径，则有一个MAX_PATH字符的缺省字符串大小限制，此限制与CreateFile函数怎样分析路径有关。

dwDesiredAccess：

指定对对象的访问类型，一个应用程序可以得到读访问、写访问、读_写访问或设备查询访问等类型，此参数可以为下列值的任意一个组合值：

0：

指定对对象有设备查询访问，一个应用程序可以不通过访问设备来查询设备属性。

GENERIC_READ：

指定对象的读访问，可以读文件的数据且可移动文件中的指针，读_写访问要与GENERIC_WRITE联合使用。

GENERIC_WRITE：

指定对象的写访问，可以写文件的数据且可以移动文件指针，读_写访问要与GENERIC_READ联合使用。

dwShoreMode：

位标志集，指定对象怎样被共享，如果该参数为0，则对象不能被共享，后续对该对象进行打开操作将会失败，直到关闭句柄为止。

为达到对象共享的效果，可以用下列值中的一个或更多的组合：

FILE_SHARE_DELETE：

WindowsNT：

只要有请求删除访问，对对象后续打开操作将成功。

FILE_SHARE_READ：

只要请求读访问，那么对对象的后续打开操作将成功。

FILE_SHARE_WRITE：

只要请求写访问，那么对对象的后续打开操作将成功。

lpSecurityAttributes:

指向一个SECURITY_ATTRIBUTES结构的指针，该结构决定了应用程序能否继承返回句柄，如果该参数为NULL，则返回句柄不能被继承。

dwCreationDisposition:

指定对存在的文件采取哪种措施，且当文件不存在时采用哪种措施，此函数必须是下列值中的一个：

CREAT_NEW:

创建一个新文件，如果文件存在，则函数调用失败。

CREAT_ALWAYS:

创建一个新文件，如果文件存在，函数重写文件且清空现有属性。

OPEN_EXISTING:

打开文件，如果文件不存在，则函数调用失败。

OPEN_ALWAYS:

如果文件存在，则打开文件。

如果文件不存在，则函数就像dwCreationDisposition参数取CREATE_NEW值一样创建文件。

TRUNCATE_EXISTING:

打开文件，一旦文件打开，文件被截取以便它的大小为0字节，调用函数必须用GENERIC_WRITE访问来打开文件，如果文件不存在，则函数调用失败。

dwFlagsAndAttributes:

指定文件属性和标志，该参数可取下列属性中的任何一个组合，除了其他所有文件属性覆盖FlLEATTRIBUTE_NORMAL属性：

FILE_ATTRIBUTE_ARCHIVE：

文件一定是档案文件，应用程序用此属性标志文件的备份或删除。

FILE_ATTRIBUTE_HIDDEN：

文件被隐藏，它不包括在一般目录列表中。

FILE_ATTRIBUTE_NORMAL：

文件没有其他属性设置，只要单独使用，此属性是生效的。

FILE_ATTRIBUTE_OFFLINE：

不能立即得到文件数据，表明文件数据已经被移到脱机存储器。

FILE_ATTRIBUTE_READONLY：

文件只读，应用程序可以读文件但不能写文件或删除它。

FILE_ATTRIBUTE_SYSTEM：

文件是操作系统的一部分或被操作系统单独使用。

FILE_ATTRIBUTE_TEMPORARY：

文件作暂时存储使用，文件系统试图把所有数据存储在快速访问的内存中，而不是把数据放在大容量存储器中，当不再需要临时文件时，应用程序应该删除掉它。

该参数也可取下列标志中的任何一个组合，标志的意义：

FILE_FLAG_WRITE_THROUGH:

指导系统通过瞬间缓存直接写入磁盘，系统仍能存储写操作但不能迟钝地冲刷它们。

FlLE_FLAG_0VERLAPPED：

指导系统对对象进行初始化，以便操作有足够的时间来处理返回ERROR_IO_PENDING，当完成操作时，指定事件被设置为发信号状态。

FILE_FLAG_N0_BUFFERING：

引导系统打开没有瞬间缓冲或缓存的文件，当与FILE_FLAG_0VERLAPPED结合时，标志给出最大的按时间顺序的操作，因为I／O不依靠内存管理器的时间顺序的操作，但是一些I/O操作将长一些，因为数据没有在缓存中。

当与用FILE_FLAG_NO_BUFFERING打开的文件一起工作时，应用程序定满足某种要求：

文件访问必须从文件内的字节位移处开始，该文件为容量扇区大小的整数倍，文件访问是为字节的数目，该字节的数目为容量扇区大小的整数倍，例如，如果扇区大小为512字节，则应用程序请求512，1024或2048字节的读或写，但不是335，918或7171字节。

缓冲区对读和写操作的地址一定是扇区定位，（定位在整数倍于容量扇区大小的内存的地址中）。

把缓冲区调整在容量扇区大小整数倍的一个方法是用VirtualAlloc分配缓冲区，它分配地址上调整的内存，该地址是操作系统内存页面大小的整数倍，因为无论是内存板面还是容量扇区大小都是2的乘方数，此内存也被调整在为容量扇区大小整数倍地址上。

应用程序可以通过调用GetDiskFreeSpace函数来决定容量扇区大小。

FILE_FLAG_RANDOM_ACCESS:

显示文件可以被随意访问，系统可有它作为暗示从优化文件缓存。

FILE_FLAG_SEQUENTIAL_SCAN：

显示文件从开头到结尾按顺序被访问，系统可用它作为暗示以优化文件缓存，如果应用顺序为随意访问而移动文件指针，则会出现最优缓存，但是仍允许正确的操作。

指定此标志可以增加应用程序的，应用程序用顺序访问读大文件，性能增益性能。

对应用程序来说更加突出，该应用程序大都是按顺序读大文件，但是偶尔也会忽略较少字节的文件。

FILE_FLAG_DELETE_0N_CLOSE:

显示所以句柄被关闭之后，操作系统将立即删除文件，但并不仅是指定的FILE_FLAG_DELETE_ON_CLOSE句柄。

如果不用FILE_SHARE_DELETE，则对文件的顺序打开请求失败。

FILE_FLAG_BACKUP_SEMANTlCS:

在WindowsNT中显示为备件和存储操作，打开或创建文件，系统保证调用应用程序忽略文件安全检查，只要它有需要的特权，相交的特权是SE_BACKUP_NAME和SE_KESTOKE_NAME。

可以设置此标志以得到一个指向目录的句柄，目标句柄可以被传递到一些Win32函数中以代替文件句柄。

FILE_FLAG_POSIX_SEMANTIC：

显示根据POSIX规则，文件将被访问，它包括允许带有名的多文件，仅在“1”时不一样，对文件系统支持此命名，注意要当此选择时要小心，因为用此标志创建的文件不能被为MS—DOS或16位Windows而写的应用程序所访问。

FILE_FLAG_OPEN_REPARSE_POINT:

指定此标志NTFS复发点的复发行为，当打开文件时，返回文件句柄，不管控制复发点的筛选程序是否可操作性，此标志不可与CREATE_ALWAYS标志一起使用。

FILE_FLAG_OPEN_N0_RECALL:

显示文件数据被请求，但它应该留有远程存储器中，它不应该传输回当地存储器，此标志是指定给远程存储系统或HierarhicalStorageManagementsystem系统的使用。

如果CreateFile函数打开命名的管道的客户端，则dwFlagsAndAttributes参数可包含Service信息。

SecurityQuality特性，有关更多的信息，参见ImpersonationLevels当调用应用程序指定SECURTY_SQOS_PRESENT标志，则dwFlagsAndAttributes参数可包括下列值的一个多或多个值：

SECURITY_ANONYMOUS：

指定在Anonymous人格化模仿客户。

SECURITY_IDENTIFICATI0N:

指定在Identification人格化层次人格化模仿客户。

SECURITY_IMPERSONATI0N：

指定在Impersonation人格化层次人格化模仿客户。

SECURITY_DELEGATI0N：

指定在Delegation人格化层次人格化模仿客户。

SECURITY_CONTEXT—TRACKINGS：

指定安全轨道模块是动态的，如果没有指定此标志，则安全轨道模块足表态的。

SECURITY_EFFECTIVE_ONLY:

指定服务器可以得到只有客户安全描述表的激活方面，如果没有指定此标志则可得到客户安全描述表的所有方面。

此标志允许客户来限制工作组和访问权，当人格化模仿客户端时，服务器可用此工作组和访问权。

hTemplateFile：

指定用GENERIC_READ路径访问模板文件的句柄，模板文件为创建的文件提供文件属性和扩展属性。

返回值：

如果函数调用成功，返回值为指向指定文件的打开句柄；如果指定文件在函数调用之前已经存在，且dwCreationDisposition为CREATE_ALWAYS或OPEN_ALWAYS，则对GetLastError的调用返回ERROR_ALREADY_EXISTS（即使函数调用成功）；如果在函数调用之前文件不存在，则GetLastError返回零。

如果函数调用失败，返回值为INVALID_HANDLE_VALUE有关更多详细信息调用GetLastError。

备注：

用CloseHande函数来关闭CreateFile函数返回的句柄。

如果所述为dwDesiredAccess指定零允许应用程序查询设备属性而不是实际地访问设备。

此类型访问查询是有用的，例如，如果应用程序想决定软驱磁盘的大小和支持的格式化，可以不需要驱动器中的软盘。

头文件：

winbase.h

二、ReadFile和WriteFile函数

简介：

这两个函数的参数数目和基本含义大致相同，第一个参数指定读写文件的文件名，第二个参数是一个缓冲区，在ReadFile中它作为存放数据的目的地，而WriteFile中它是写入文件的数据的来源，第三个参数指定读写文件的长度，而第四个参数是实际读写的数目，单位是字节，最后一个参数只对异步传输模式有意义，在非异步传输模式中这个值被设定为NULL，而在异步传输模式中需要提供一个OVERLAPPED结构的参数。

ReadFile

函数功能：

该函数从文件指针指示的位置开始从文件读数据，在读操作完成以后，如果文件句柄不是用重叠属性来创建，则文件指针用实际读的字节数来调整。

如果文件句柄为重叠的输入和输出（I／O）操作而创建，则应用程序必须在读操作之后调整文件指针的位置。

函数原型：

BOOLReadFile（HANDLEhFile，LPVOIDlpBuffer，

DWORDnNumbeOfBytesToRead，LPDWORDlpNumberOfBytesRead，LPOVERLAPPEDlpOverlapped）；

参数：

hFile：

指向要读的文件的句柄，文件句柄一定用GENERIC_READ对文件的访问来创建。

WindowsNT：

对于异步读操作，hFile可为任何一个句柄，该句柄可以通过CreateFile函数用FILE_FLAG_OVERLAPPED标志来打开或通过插孔或接收函数返回的插孔句柄来打开。

lpBuffer：

指向一个从文件存取数据的缓冲区的指针。

nNumberOfBytesToRead：

从文件读的字节数目。

lpNumberOfBytesRead：

指向一个读字节数的指针，在做任何工作或错误检测之前，Read门e把此值设置为零，当ReadFile在命名管道上返回TRUE时，如果此参数为零，则用nNumberOfBytesToWrite调用WriteFile函数的信息模块将管道的另一端设置为零。

WindowsNT：

如果lpOverlapped为NULL，则lpNumberOfBytesRead不为NULL；如果lpOverlapped不为NULL，则lpNumberOfBytesRead可以为NULL，如果这是—一个重叠写操作，则可通过调用GetOverlappedResuIt来得到读字节的数目，如果hFile与一个I/O完成端口有关，则可通过调用GetQueuedCompletionStatus来得到读字节的数目。

lpOverlapped：

指向一个OVERLAPPED结构的指针，如果用FILE_FLAG_OVERLAPPED来创建hFile，则需要此结构，如果用FILE_FLAG_OVERLAPPED来打开hFile，则lpOverlapped参数一定不是NULL。

它必须指向一个有效的OVERLAPPED结构，如果hFile是由FILE_FLAG_OVERLAPPED创建且lpOverlapped为NULL，则函数可不正确地记录关于读操作是完全的。

如果hFile用FILE_FLAG_OVERLAPPED打开，且lpOverlapped不为NULL，则读操作在OVERLAPPED结构中指定的位移处开始，在完成读操作之前，且ReadFile可以返回在这种情况下ReadFile返回FALSE且GetLastError函数返回ERROR_IO_PENDING这使在读操作完成时，调用应用系统继续。

在OVERLAPPED结构中指定的事件被设置为读操作完成的发送信号状态。

如果hFile不用FlLE_FLAG_OVERLAPPED打开，且lpOverlapped不为NULL，则读操作在当前文件位置开始且至操作完成，ReadFile函数返回。

如果hFile不用FILE_FLAG_OVERLAPPED打开，且lpOverlapped不为NULL，则读操作OVERLAPPED结构指定的位移处开始，直到操作完成，ReadFile函数返回。

返回值：

当下列之一的为真时，ReadFile函数返回。

写操作在管道写终端完成，请求读的字节数目或出现错误。

如果函数调用成功，则返回值为非零值。

如果返回值为非零值，且读字节数目为零，则在读操作时文件指针超出文件当前终端。

但是，如果文件用FILE_FLAG_OVERLAPPED打开且lpOverlapped不为NULL，则返回值为FALSE,且当文件指针超过文件当前终端时,GetLastError函数返回ERROR_HANDLE_EOF。

如果函数调用失败，则返回值为零。

若想获得更多错误信息，请调用GetLasError函数。

备注：

如果文件的一部分由另一个应用程序锁定，且读操作重叠锁定端口，则函数调用失败。

当与用FILE_FLAG_NO_BUFFERING打开的文件一起工作时，应用程序必须满足某种需要。

文件访问一定在文件内字节位移处开始，该文件为容量扇区大小的整数倍，为决定一个容量扇区的大小，调用GetDiskFreeSpace函数。

文件访问必须是对于字节数目的访问，该字节数目为容量扇区大小的整数倍，例如如果扇区大小为512字节，应用程序可以请求512，1024或2048字节的读和写访问，但不是335，981或7171字节缓冲区对读、写操作的地址一定为对齐扇区（在内存地址上对齐，该内存为容量扇区大小的整数倍）一种对齐扇区的缓区器的方法是用VirtualAlloc函数来分配缓冲区，此函数分配内存，该内存在为系统页面大小的整数倍的地址上对齐，因为无论是页面还是扇区大小都是2的幂，用系统页面大小的倍数对齐的内存也可用容量扇区大小的倍数来对齐调整（‘对齐’改为‘调整’）。

在读操作正在有缓冲区时访问输入缓冲区，则可导致输入缓冲区数据的破坏，直到读操作完成为止，应用程序才能读、写重分配或释放一个正被一个读操作使用，输入缓冲区。

如果一个命名的管道正在信息模块中读且下一个信息比nNumberOfBylesToRead参数长，则ReadFile返回FALSE是GetLasIError返回ERROR_MODE_DATA，剩—下的信息也许通过下一次对ReadFile或PeekNamePipe函数的调用来读。

‘

当从通信设备来读数据时，且当用SetCommTimeouts和GetCommTimeouts函数来设置和枪取超时时，ReadFile的行为由当前通信超时来操纵，如果不能设置超时时，则会出现不可预料的结果，有关信息超时更详细的资料，参见COMMTIMEOUTS。

如果ReadFile试图从缓冲区太小的邮件插孔读数据，则函数返回FALSE且GetLastError函数返回ERROR_INSUFFICENT_BUFFER。

如果匿名写通道句柄已经被关闭且ReadFile试图用相应的匿名读通道句柄来读，则函数返回FALSE且GetLastError返回ERROR_BROKEN_PIPE。

当不足够多的明显异步I／O请求时，ReadFile函数可能失败且返回ERROR_INVALID_USER_BUFFER或EERROR_NOT_ENOUGH_MEMORY。

ReadFile代码为状态文件终端而检测与异步和同步读操作不同。

当一个同步读操作到达文件末尾时，ReadFile返回TRUE且把lpNumberOfBytesResd设置为零，下列样本代码用来为同步读操作文件末尾的检测。

//Attemptasynchronousreadoperation

bResult=ReadFile（hFile,&inBuffer,nBytesToRead,&nBytesRead,NULL）;

//Checkforendoffile

if（bResult&&nBytesRead==0）

{//we’reattheendofthefile}

在起始的ReadFile调用期间，或下一次异步操作期间，一个异步读操作可以遇到文件的末尾。

如果对于异步读操作在ReadFile时间EOF被删除，则ReadFile返回FALSE且GetLastError返回ERROR_HANDLE_EOF。

如果在下一次异步操作期间EOF被删除，对GetOverlappedResuIt的调用，可以导致操作返回FALSE且GetError返回ERROR_HANDLE_EOF。

用Cancel函数来取消所有未知异步I/O操作，此函数只取消由关于指定文件句柄的调用线程发布的操作，被取消的I/O操作用错误ERROR_OPERATION_ABORTED来完成。

如果试图从一个没有软盘的软驱中读数据，则系统显示一个信息框告诉用户重新执行此操作，为避免系统显示此信息框，用SEM_NOOPENFILEERRORBOX来调用SetErrorMode函数。

头文件：

winbase.h

WriteFile

函数功能：

该函数把数据写入文件且用于同步和异步操作，函数把数据写入文件的位置在由文件指针显示的位置，在写操作完成之后，文件指针用实际写入的字节数目来调整，除了当文件用FILE_FLAG_0VERLAPPED打开的之外，如果文件句柄为重叠的I／O创建，则应用程序必须在写操作完成之后必须调整文件指针的位置。

函数原型：

BOOLWriteFile（HANDLEhFile，LPCVOIDlpBuffer，

DWORDnNumber0fBytesToWrite，LPDWORDlpNumberOfBytesWritten，LPOVERLAPPEDlpOverlapped）；

参数：

hFile：

指向要写入数据的文件的句柄，文件句柄一定已用对文件的GENERIC_WRITE访问创建。

WindowsNT：

对于异步写操作，hFile可以为通过CreateFile函数由FILE_FLAG_OVERLAPPED标志，来打的任何一个句柄，或一个通过插孔或接收函数返回的插孔的句柄。

lpBuffer：

指向含有被写入文件的数据的缓冲区的指针。

nNumberOfBytesToWrite:

写入文件的字节数目零值指定了一个空写操作，一个空写操作不写任何字节但会使时间堆栈改变。

通过网络的命令的通道写操作局限于65，535字节。

lpNumberOfBytesWritten:

指向通过此函数调用写入的字节数目，在做任何工作或检测错之前，WriteFile将此值设为零。

WindowsNT：

如果lpOverlapped为NULL，则lpNumberOfBytesWrit不能为NULL；如果lpOverlapped不为NULL，则lpNumberOfBytes可以为NULL。

如果这是一个重叠的写操作，则可通过调用GetOverlappedResult得到写入的字节数目，如果hFile与一个I/O完成端口有关，则可通过调用GetQueuedCompletionStatus得到写入的字节数目。

lpOverlapped：

指向一个OVERLAPPED结构的指针，如果hFile用FILE_FLAG_0VERLAPPED打开,则需要的结构，如果hFile用FILE_FLAG_OVERLAPPED打开，则lpOverlapped参数一定不为NULL，它一定指向一个有效的OVERLAPPE结构，如果hFile用FILE_FLAG_OVERLAPPED打开且lpOverlapped为NULL，则函数可不正确地记录写操作完成。

如果hFile用FILE_FLAG—0VERLAPPED打开且lp