| 术语 | setfilepointer |
| 释义 | SetFilePointer 语法： C++ DWORD WINAPI SetFilePointer( __in HANDLE hFile, __in LONG lDistanceToMove, __inout_opt PLONG lpDistanceToMoveHigh, __in DWORD dwMoveMethod ); SetFilePointer函数 移动指定文件的文件指针。 这个函数指针存储在两个文件的长值。若要使用文件指针会比一个长值大，更容易使用SetFilePointerEx功能。 参数 hFile [in] 阿处理该文件。 文件句柄必须创建与GENERIC_READ或GENERIC_WRITE访问权限。有关更多信息，请参阅文件安全性和访问权限。 lDistanceToMove [in] 低位32签署的值，指定的字节数移动文件指针位。 如果lpDistanceToMoveHigh不为NULL，lpDistanceToMoveHigh和lDistanceToMove形成一个单一的64位有符号的值，指定的距离移动。 如果lpDistanceToMoveHigh为NULL，lDistanceToMove是一个32位有符号的值。阿为着在文件的文件指针，负值移动文件指针返回lDistanceToMove移动正面价值。 lpDistanceToMoveHigh [中，指出，可选] 向高阶的32位签名的64位指针移动的距离。 如果您不需要高阶32位，这个指针必须设置为NULL。 当不空，此参数也接收高阶对新文件指针DWORD值。有关更多信息，请参阅本主题中的备注部分。 dwMoveMethod [in] 该文件的指针移动的起点。 此参数可以是下列值之一。 ValueMeaning FILE_BEGIN 0The的出发点是零(0)或文件的开头。 FILE_CURRENT 1The的出发点是文件的指针的当前值。 FILE_END 2The的出发点是，当前文件结束的位置。 返回值 如果函数成功和lpDistanceToMoveHigh为NULL，则返回值是低位的新文件指针DWORD中。 Note If the function returns a value other than INVALID_SET_FILE_POINTER, the call to SetFilePointer has succeeded.您不需要调用GetLastError函数。 IF函数是成功和lpDistanceToMoveHigh不为NULL，则返回值是低位双字节值的新文件指针和lpDistanceToMoveHigh包含高阶新文件指针DWORD中。 如果函数失败，返回值是INVALID_SET_FILE_POINTER。为了获得更多错误信息，调用GetLastError。 如果一个新的文件指针是一个负值，函数失败，文件指针没有移动，并GetLastError函数返回的代码是ERROR_NEGATIVE_SEEK。 如果lpDistanceToMoveHigh是NULL，新的文件中的位置不适合在32位的值，函数失败并返回INVALID_SET_FILE_POINTER。 注意：由于INVALID_SET_FILE_POINTER是一个低序新文件指针双字节值有效的值，您必须同时检查函数的返回值和错误代码GetLastError函数返回确定是否发生错误。如果出现错误，在SetFilePointer返回值是INVALID_SET_FILE_POINTER和GetLastError返回值比NO_ERROR等。有关代码示例，演示了如何检查故障，请参阅本主题中的备注部分。 备注 文件指针是由hFile参数值确定不用于重叠读取和写入操作。您不能使用的句柄，如不寻求管道或设备的通信设备的SetFilePointer功能。 要指定偏移重叠操作 使用OFFSET和OVERLAPPED结构OffsetHigh成员。 要确定文件类型hFile 使用GetFileType功能。 有关如何确定一个文件指针的位置信息，请参阅文件指针定位。 时要小心设置在多线程应用程序文件指针。您必须同步访问共享资源。例如，一个线程共享文件处理应用程序，更新文件指针，从文件中读取要保护使用临界区对象或互斥对象这个序列。有关更多信息，请参阅临界区对象和互斥对象。 如果hFile句柄打开的FILE_FLAG_NO_BUFFERING标志设置，应用程序可以将文件指针只扇区对齐位置。甲部门不结盟的立场是这一立场是卷的部门规模的整数倍数。应用程序可以通过调用GetDiskFreeSpace函数卷部门的规模。 若应用程序调用的距离SetFilePointer移动值导致公司不能部门不结盟和句柄与FILE_FLAG_NO_BUFFERING打开，该功能失败，并且GetLastError返回ERROR_INVALID_PARAMETER。 这不是一个错误设置文件指针超出文件末尾的位置。该文件的大小不会增加，直到您调用SetEndOfFile，WriteFile，或WriteFileEx功能。写操作增加了文件的大小文件指针的位置加上书面缓冲区，在干预的结果，未初始化的字节大小。 If the return value is INVALID_SET_FILE_POINTER and if lpDistanceToMoveHigh is non-NULL, an application must call GetLastError to determine whether or not the function has succeeded or failed.下面的代码示例演示了这一局面。 // Case One: calling the function with lpDistanceToMoveHigh == NULL // Try to move hFile file pointer some distance DWORD dwPtr = SetFilePointer( hFile, lDistance, NULL, FILE_BEGIN ); if (dwPtr == INVALID_SET_FILE_POINTER) // Test for failure { // Obtain the error code. DWORD dwError = GetLastError() ; // Deal with failure // . . . } // End of error handler // // Case Two: calling the function with lpDistanceToMoveHigh != NULL // Try to move hFile file pointer a huge distance DWORD dwPtrLow = SetFilePointer( hFile, lDistLow, &lDistHigh, FILE_BEGIN ); // Test for failure if ( dwPtrLow == INVALID_SET_FILE_POINTER && GetLastError() != NO_ERROR ) { // Deal with failure // . . . } // End of error handler 虽然参数lpDistanceToMoveHigh是用于操作大型文件，该参数的值时，应设置移动任何大小的文件。如果它被设置为NULL，然后lDistanceToMove有一个最大值为2 ^ 31-2，2千兆字节或减2，因为所有文件指针的值是有符号的值。因此，如果有，甚至连一个小的文件的机会，以增加其规模而言，是最适当的处理是一个巨大的文件的文件，并与64位文件指针。随着文件在NTFS文件系统压缩和稀疏文件，很可能有大量文件，这些文件即使基础量不是很大。 如果lpDistanceToMoveHigh不为NULL，则lpDistanceToMoveHigh和lDistanceToMove形成一个单一的64位有符号的值。该lDistanceToMove参数视为低32位的价值，以及高阶32位，这意味着lpDistanceToMoveHigh是lDistanceToMove符号扩展lpDistanceToMoveHigh。 为了从零文件指针(0)到2千兆字节，lpDistanceToMoveHigh必须设置为空或lDistanceToMove符号扩展。要移动作为一个单独的64位指针数量超过2千兆字节，使用lpDistanceToMoveHigh和lDistanceToMove。 For example, to move in the range from 2 gigabytes to 4 gigabytes set the contents of lpDistanceToMoveHigh to zero (0), or to –1 for a negative sign extension of lDistanceToMove. 若要使用64位文件指针，您可以声明一个龙，当作了上半的64位文件指针它，并通过其在lpDistanceToMoveHigh地址。此意味着您必须将其作为一个逻辑单元，它可以导致错误两个不同的变量。最好是使用LARGE_INTEGER结构，通过使用工会适当的要素的64位值，并通过两个32位值。 另外，最好使用一个函数来隐藏接口SetFilePointer。下面的代码示例演示了这一局面。 __int64 myFileSeek (HANDLE hf, __int64 distance, DWORD MoveMethod) { LARGE_INTEGER li; li.QuadPart = distance; li.LowPart = SetFilePointer (hf, li.LowPart, &li.HighPart, MoveMethod); if (li.LowPart == INVALID_SET_FILE_POINTER && GetLastError() != NO_ERROR) { li.QuadPart = -1; } return li.QuadPart; } 您可以使用SetFilePointer来确定一个文件的长度。要做到这一点，使用FILE_END为dwMoveMethod并寻求位置零(0)。文件偏移返回是该文件的长度。然而，这一做法可以有意想不到的副作用，例如，未能保存当前文件指针，以便程序可以返回到该位置。最好是用GetFileSize代替。 您还可以使用SetFilePointer函数来查询当前文件指针的位置。要做到这一点，指定一个FILE_CURRENT移动方法以及零距离(0)。 实例 如需附加文件中的代码示例，请参阅追加一个文件到另一个文件。 要求： 最低支持：client－Windows 2000专业版 最低支持server－Windows 2000服务器 HeaderWinBase.h(头文件：winuser.h) LibraryKernel32.lib DLLKernel32.dll 参见 文件管理函数 GetDiskFreeSpace GetFileSize GetFileType ReadFile ReadFileEx SetEndOfFile SetFilePointerEx WriteFile WriteFileEx 如果有任何问题和意见，请发送给微软(wsddocfb@microsoft.com) 生成日期：2009年9月3日 ＝＝英文原文＝＝SetFilePointer Function Moves the file pointer of the specified file. This function stores the file pointer in two LONG values. To work with file pointers that are larger than a single LONG value, it is easier to use the SetFilePointerEx function. Syntax C++ DWORD WINAPI SetFilePointer( __in HANDLE hFile, __in LONG lDistanceToMove, __inout_opt PLONG lpDistanceToMoveHigh, __in DWORD dwMoveMethod ); Parameters hFile [in] A handle to the file. The file handle must be created with the GENERIC_READ or GENERIC_WRITE access right. For more information, see File Security and Access Rights . lDistanceToMove [in] The low order 32-bits of a signed value that specifies the number of bytes to move the file pointer. If lpDistanceToMoveHigh is not NULL, lpDistanceToMoveHigh and lDistanceToMove form a single 64-bit signed value that specifies the distance to move. If lpDistanceToMoveHigh is NULL, lDistanceToMove is a 32-bit signed value. A positive value for lDistanceToMove moves the file pointer forward in the file, and a negative value moves the file pointer back. lpDistanceToMoveHigh [in, out, optional] A pointer to the high order 32-bits of the signed 64-bit distance to move. If you do not need the high order 32-bits, this pointer must be set to NULL. When not NULL, this parameter also receives the high order DWORD of the new value of the file pointer. For more information, see the Remarks section in this topic. dwMoveMethod [in] The starting point for the file pointer move. This parameter can be one of the following values. ValueMeaning FILE_BEGIN 0The starting point is zero (0) or the beginning of the file. FILE_CURRENT 1The starting point is the current value of the file pointer. FILE_END 2The starting point is the current end-of-file position. Return Value If the function succeeds and lpDistanceToMoveHigh is NULL, the return value is the low-order DWORD of the new file pointer. Note If the function returns a value other than INVALID_SET_FILE_POINTER, the call to SetFilePointer has succeeded. You do not need to call GetLastError . If function succeeds and lpDistanceToMoveHigh is not NULL, the return value is the low-order DWORD of the new file pointer and lpDistanceToMoveHigh contains the high order DWORD of the new file pointer. If the function fails, the return value is INVALID_SET_FILE_POINTER. To get extended error information, call GetLastError. If a new file pointer is a negative value, the function fails, the file pointer is not moved, and the code returned by GetLastError is ERROR_NEGATIVE_SEEK. If lpDistanceToMoveHigh is NULL and the new file position does not fit in a 32-bit value, the function fails and returns INVALID_SET_FILE_POINTER. Note Because INVALID_SET_FILE_POINTER is a valid value for the low-order DWORD of the new file pointer, you must check both the return value of the function and the error code returned by GetLastError to determine whether or not an error has occurred. If an error has occurred, the return value of SetFilePointer is INVALID_SET_FILE_POINTER and GetLastError returns a value other than NO_ERROR. For a code example that demonstrates how to check for failure, see the Remarks section in this topic. Remarks The file pointer that is identified by the value of the hFile parameter is not used for overlapped read and write operations. You cannot use the SetFilePointer function with a handle to a non-seeking device such as a pipe or a communications device. To specify the offset for overlapped operations Use the Offset and OffsetHigh members of the OVERLAPPED structure. To determine the file type for hFile Use the GetFileType function. For information about how to determine the position of a file pointer, see Positioning a File Pointer . Be careful when you set a file pointer in a multi-threaded application. You must synchronize access to shared resources. For example, an application with threads that share a file handle, update the file pointer, and read from the file must protect this sequence by using a critical section object or mutex object. For more information, see Critical Section Objects and Mutex Objects . If the hFile handle is opened with the FILE_FLAG_NO_BUFFERING flag set, an application can move the file pointer only to sector-aligned positions. A sector-aligned position is a position that is a whole number multiple of the volume sector size. An application can obtain a volume sector size by calling the GetDiskFreeSpace function. If an application calls SetFilePointer with distance to move values that result in a position not sector-aligned and a handle that is opened with FILE_FLAG_NO_BUFFERING, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER. It is not an error to set a file pointer to a position beyond the end of the file. The size of the file does not increase until you call the SetEndOfFile , WriteFile , or WriteFileEx function. A write operation increases the size of the file to the file pointer position plus the size of the buffer written, which results in the intervening bytes uninitialized. If the return value is INVALID_SET_FILE_POINTER and if lpDistanceToMoveHigh is non-NULL, an application must call GetLastError to determine whether or not the function has succeeded or failed. The following code example shows you that scenario. // Case One: calling the function with lpDistanceToMoveHigh == NULL // Try to move hFile file pointer some distance DWORD dwPtr = SetFilePointer( hFile, lDistance, NULL, FILE_BEGIN ); if (dwPtr == INVALID_SET_FILE_POINTER) // Test for failure { // Obtain the error code. DWORD dwError = GetLastError() ; // Deal with failure // . . . } // End of error handler // // Case Two: calling the function with lpDistanceToMoveHigh != NULL // Try to move hFile file pointer a huge distance DWORD dwPtrLow = SetFilePointer( hFile, lDistLow, &lDistHigh, FILE_BEGIN ); // Test for failure if ( dwPtrLow == INVALID_SET_FILE_POINTER && GetLastError() != NO_ERROR ) { // Deal with failure // . . . } // End of error handler Although the parameter lpDistanceToMoveHigh is used to manipulate huge files, the value of the parameter should be set when moving files of any size. If it is set to NULL, then lDistanceToMove has a maximum value of 2^31–2, or 2 gigabytes less 2, because all file pointer values are signed values. Therefore, if there is even a small chance for the file to increase to that size, it is best to treat the file as a huge file and work with 64-bit file pointers. With file compression on the NTFS file system, and sparse files , it is possible to have files that are large even if the underlying volume is not very large. If lpDistanceToMoveHigh is not NULL, then lpDistanceToMoveHigh and lDistanceToMove form a single 64-bit signed value. The lDistanceToMove parameter is treated as the low-order 32 bits of the value, and lpDistanceToMoveHigh as the high-order 32 bits, which means that lpDistanceToMoveHigh is a sign extension of lDistanceToMove. To move the file pointer from zero (0) to 2 gigabytes, lpDistanceToMoveHigh must be set to either NULL or a sign extension of lDistanceToMove. To move the pointer more than 2 gigabytes, use lpDistanceToMoveHigh and lDistanceToMove as a single 64-bit quantity. For example, to move in the range from 2 gigabytes to 4 gigabytes set the contents of lpDistanceToMoveHigh to zero (0), or to –1 for a negative sign extension of lDistanceToMove. To work with 64-bit file pointers, you can declare a LONG, treat it as the upper half of the 64-bit file pointer, and pass its address in lpDistanceToMoveHigh. This means that you have to treat two different variables as a logical unit, which can cause an error. It is best to use the LARGE_INTEGER structure to create a 64-bit value and pass the two 32-bit values by using the appropriate elements of the union. Also, it is best to use a function to hide the interface to SetFilePointer. The following code example shows you that scenario. __int64 myFileSeek (HANDLE hf, __int64 distance, DWORD MoveMethod) { LARGE_INTEGER li; li.QuadPart = distance; li.LowPart = SetFilePointer (hf, li.LowPart, &li.HighPart, MoveMethod); if (li.LowPart == INVALID_SET_FILE_POINTER && GetLastError() != NO_ERROR) { li.QuadPart = -1; } return li.QuadPart; } You can use SetFilePointer to determine the length of a file. To do this, use FILE_END for dwMoveMethod and seek to location zero (0). The file offset returned is the length of the file. However, this practice can have unintended side effects, for example, failure to save the current file pointer so that the program can return to that location. It is best to use GetFileSize instead. You can also use the SetFilePointer function to query the current file pointer position. To do this, specify a move method of FILE_CURRENT and a distance of zero (0). Examples For a code example of appending files, see Appending One File to Another File . Requirements Minimum supported clientWindows 2000 Professional Minimum supported serverWindows 2000 Server HeaderWinBase.h (include Windows.h) LibraryKernel32.lib DLLKernel32.dll See Also File Management Functions GetDiskFreeSpace GetFileSize GetFileType ReadFile ReadFileEx SetEndOfFile SetFilePointerEx WriteFile WriteFileEx Send comments about this topic to Microsoft Build date: 9/3/2009 ＝＝原始网址＝＝http://msdn.microsoft.com/en-us/library/aa365541(VS.85).aspx\n |
| 随便看 |
|
windows api函数参考手册包含2258条windows api函数文档，详细介绍nodejs、java、rust调用windows api的方法技巧，是学习windows api编程的入门中文文档。