| Previous |Main |Next |Site Index |Download |Disclaimer |Privacy |

WINDOWS THREAD SYNCHRONIZATION REFERENCES 2

GetEnvironmentVariable()

SetEnvironmentVariable()

GetEnvironmentStrings()

FreeEnvironmentStrings()

CreateWaitableTimer()

Parameters

lpTimerAttributes - [in] Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new timer object and determines whether child processes can inherit the returned handle. If lpTimerAttributes is NULL, the timer object gets a default security descriptor and the handle cannot be inherited. The ACLs in the default security descriptor for a timer come from the primary or impersonation token of the creator. bManualReset - [in] If this parameter is TRUE, the timer is a manual-reset notification timer. Otherwise, the timer is a synchronization timer. lpTimerName - [in] Pointer to a null-terminated string specifying the name of the timer object. The name is limited to MAX_PATH characters. Name comparison is case sensitive. If lpTimerName is NULL, the timer object is created without a name. If lpTimerName matches the name of an existing event, semaphore, mutex, job, or file-mapping object, the function fails and GetLastError() returnsERROR_INVALID_HANDLE. This occurs because these objects share the same name space. Terminal Services:  The name can have a "Global\" or "Local\" prefix to explicitly create the object in the global or session name space. The remainder of the name can contain any character except the backslash character (\).

Windows XP Home Edition:  Fast user switching is implemented using Terminal Services sessions. The first user to log on uses session 0, the next user to log on uses session 1, and so on. Kernel object names must follow the guidelines outlined for Terminal Services so that applications can support multiple users. Windows 2000:  If Terminal Services is not running, the "Global\" and "Local\" prefixes are ignored. The remainder of the name can contain any character except the backslash character. Windows NT:  The name can contain any character except the backslash character. Windows 98/Me:  The name can contain any character except the backslash character. The empty string ("") is a valid object name.

Some Remarks

The handle returned by CreateWaitableTimer() is created with the TIMER_ALL_ACCESS access right. This handle can be used in any function that requires a handle to a timer object.  Any thread of the calling process can specify the timer object handle in a call to one of the wait functions.  Multiple processes can have handles to the same timer object, enabling use of the object for interprocess synchronization.

1. A process created by the CreateProcess() function can inherit a handle to a timer object if thelpTimerAttributes parameter of CreateWaitableTimer() enables inheritance.

2. A process can specify the timer object handle in a call to the DuplicateHandle() function. The resulting handle can be used by another process.

3. A process can specify the name of a timer object in a call to the OpenWaitableTimer() or CreateWaitableTimer() function.

Use the CloseHandle() function to close the handle. The system closes the handle automatically when the process terminates. The timer object is destroyed when its last handle has been closed.Windows Me/98:  CreateWaitableTimerW() is supported by the Microsoft Layer for Unicode. To use this, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows Me/98/95 Systems.

GetStdHandle()

Parameters

nStdHandle - [in] Standard device for which a handle is to be returned. This parameter can be one of the following values.

CreatePipe()

DuplicateHandle()

dwDesiredAccess - [in] Access requested for the new handle. For the flags that can be specified for each object type, see the following Remarks section. This parameter is ignored if the dwOptions parameter specifies the DUPLICATE_SAME_ACCESS flag. Otherwise, the flags that can be specified depend on the type of object whose handle is to be duplicated.

bInheritHandle - [in] Indicates whether the handle is inheritable. If TRUE, the duplicate handle can be inherited by new processes created by the target process. If FALSE, the new handle cannot be inherited.  

dwOptions - [in] Optional actions. This parameter can be zero, or any combination of the following values.

Some Remarks

The duplicate handle refers to the same object as the original handle. Therefore, any changes to the object are reflected through both handles. For example, the current file mark for a file handle is always the same for both handles. DuplicateHandle() can be called by either the source process or the target process (or a process that is both the source and target process). For example, a process can useDuplicateHandle() to create a non-inheritable duplicate of an inheritable handle, or a handle with different access than the original handle.The source process uses the GetCurrentProcess() function to get a handle to itself. This handle is a pseudo handle, butDuplicateHandle() converts it to a real process handle. To get the target process handle, it may be necessary to use some form of interprocess communication (for example, a named pipe or shared memory) to communicate the process identifier to the source process. The source process can use this identifier in theOpenProcess() function to obtain a handle to the target process. If the process that calls DuplicateHandle() is not also the target process, the source process must use interprocess communication to pass the value of the duplicate handle to the target process. DuplicateHandle() can duplicate handles to the following types of objects.

Note that DuplicateHandle() should not be used to duplicate handles to I/O completion ports. In this case, no error is returned, but the duplicate handle cannot be used.  In addition to STANDARD_RIGHTS_REQUIRED, the following access rights can be specified in the dwDesiredAccess parameter for the different object types:

1. Desktop Security and Access Rights.

2. File Security and Access Rights.

3. File-Mapping Security and Access Rights.

4. Job Object Security and Access Rights.

5. Process Security and Access Rights.

6. Registry Key Security and Access Rights.

7. Synchronization Object Security and Access Rights.

8. Thread Security and Access Rights.

9. Window-Station Security and Access Rights.

In some cases, the new handle can have more access rights than the original handle. However, in other cases, DuplicateHandle() cannot create a handle with more access rights than the original. For example, a file handle created with the GENERIC_READ access right cannot be duplicated so that it has both theGENERIC_READ and GENERIC_WRITE access right.

GetCurrentProcess()

CreateFile()

Parameters

lpFileName - [in] Pointer to a null-terminated string that specifies the name of the object to create or open.

In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend "\\?\" to the path. Windows Me/98/95:  This string must not exceed MAX_PATH characters.

dwDesiredAccess - [in] Access to the object (reading, writing, or both). You cannot request an access mode that conflicts with the sharing mode specified in a previous open request whose handle is still open. If this parameter is zero, the application can query file and device attributes without accessing the device. This is useful if an application wants to determine the size of a floppy disk drive and the formats it supports without requiring a floppy in the drive. It can also be used to test for the file's or directory's existence without opening it for read or write access.

dwShareMode - [in] Sharing mode of the object (reading, writing, both, or neither). You cannot request a sharing mode that conflicts with the access mode specified in a previous open request whose handle is still open. Doing so would result in a sharing violation (ERROR_SHARING_VIOLATION).If this parameter is zero and CreateFile succeeds, the object cannot be shared and cannot be opened again until the handle is closed. To enable other processes to share the object while your process has it open, use a combination of one or more of the following values to specify the access mode they can request when they open the object. These sharing options remain in effect until you close the handle to the object.

lpSecurityAttributes - [in] Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited. The lpSecurityDescriptor member of the structure specifies a security descriptor for the object. If lpSecurityAttributes is NULL, the object gets a default security descriptor. The ACLs in the default security descriptor for a file or directory are inherited from its parent directory. Note that the target file system must support security on files and directories for this parameter to have an effect on them. (This is indicated whenGetVolumeInformation() returns FS_PERSISTENT_ACLS).CreateFile() ignores lpSecurityDescriptor when opening an existing file, but continues to use the other structure members.

dwCreationDisposition - [in] Action to take on files that exist, and which action to take when files do not exist. For more information about this parameter, see the Remarks section. This parameter must be one of the following values.

dwFlagsAndAttributes - [in] File attributes and flags. The following file attributes and flags are used only for file objects, not other types of objects created by CreateFile(). When CreateFile() opens an existing file, it combines the file flags with existing file attributes, and ignores any supplied file attributes.  This parameter can include any combination of the file attributes (noting that all other file attributes override FILE_ATTRIBUTE_NORMAL).

This parameter can also include any combination of the following flags.

If the CreateFile() function opens the client side of a named pipe, the dwFlagsAndAttributes parameter can also contain Security Quality of Service information. When the calling application specifies the SECURITY_SQOS_PRESENT flag, the dwFlagsAndAttributes parameter can contain one or more of the following values.

hTemplateFile - [in] Handle to a template file, with the GENERIC_READ access right. The template file supplies file attributes and extended attributes for the file being created. This parameter can be NULL. If opening an existing file, CreateFile() ignores the template file. Windows Me/98/95:  The hTemplateFile parameter must be NULL. If you supply a handle, the call fails and GetLastError() returns ERROR_NOT_SUPPORTED.

Some Remarks

Use the CloseHandle() function to close an object handle returned by CreateFile(). Windows Server 2003, Windows XP, Windows 2000:  A sharing violation will occur if an attempt is made to open a file or directory for deletion on a remote computer when the value of the dwDesiredAccess parameter is theDELETE access flag OR'ed with any other access flag, and the remote file or directory has not been opened with FILE_SHARE_DELETE. To avoid the sharing violation in this scenario, open the remote file or directory with theDELETE access right only or call DeleteFile() without first opening the file or directory for deletion. Some file systems, such as NTFS, support compression or encryption for individual files and directories. On volumes formatted for such a file system, a new file inherits the compression and encryption attributes of its directory. You cannot use CreateFile() to control compression on a file or directory.

Windows Server 2003, Windows XP, Windows 2000:  For backward compatibility purposes, CreateFile() does not apply inheritance rules when you specify a security descriptor inlpSecurityAttributes. To support inheritance, functions that later query the security descriptor of this object may heuristically determine and report that inheritance is in effect. For Windows Me/98/95:  CreateFileW() is supported by the Microsoft Layer for Unicode. To use this, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.

Files

If you are attempting to create a file on a floppy drive that does not have a floppy disk or a CD-ROM drive that does not have a CD, the system displays a message box asking the user to insert a disk or a CD, respectively. To prevent the system from displaying this message box, call the SetErrorMode() function with SEM_FAILCRITICALERRORS. Windows Server 2003, Windows XP, Windows 2000:  If CREATE_ALWAYS and FILE_ATTRIBUTE_NORMAL are specified, CreateFile() will fail and set the last error to ERROR_ACCESS_DENIED if the file exists and has the FILE_ATTRIBUTE_HIDDEN or FILE_ATTRIBUTE_SYSTEM attribute. To avoid the error, specify the same attributes as the existing file.

If you rename or delete a file, then restore it shortly thereafter, the system searches the cache for file information to restore. Cached information includes its short/long name pair and creation time. Windows Me/98/95:  This remark does not apply. If you call CreateFile() on a file that is pending deletion as a result of a previous call toDeleteFile(), the function fails. The operating system delays file deletion until all handles to the file are closed. GetLastError() returns ERROR_ACCESS_DENIED. When an application creates a file across the network, it is better to useGENERIC_READ | GENERIC_WRITE than to use GENERIC_WRITE alone. The resulting code will be faster because the redirector can use the cache manager and send fewer SMBs with more data. This combination also avoids an issue where writing to the file across the network can occasionally returnERROR_ACCESS_DENIED.

Directories

An application cannot create a directory with CreateFile(); it must call CreateDirectory() or CreateDirectoryEx() to create a directory. Opening a directory with CreateFile() requires the FILE_FLAG_BACKUP_SEMANTICS flag. When using CreateFile() to open a directory during defragmentation of a FAT or FAT32 volume, do not specify the MAXIMUM_ALLOWED access right. Access to the directory will be denied if this is done. Specify the GENERIC_READ access right instead.

Physical Disks and Volumes

You can use the CreateFile() function to open a physical disk drive or a volume. The function returns a handle that can be used with the DeviceIoControl() function. This enables you to access the disk's partition table. It is potentially dangerous to do so, since an incorrect write to a disk could make its contents inaccessible. The following requirements must be met for such a call to succeed:

1. The caller must have administrative privileges.

2. The dwCreationDisposition parameter must have the OPEN_EXISTING flag.

3. When opening a volume or floppy disk, the dwShareMode parameter must have the FILE_SHARE_WRITE flag.

When opening a physical drive, x, thelpFileName string should be of the form: \\.\PHYSICALDRIVE<x>

Hard disk numbers start at zero. The following table shows some example physical drive strings.

When opening a volume or floppy drive, the lpFileName string should be of the form: \\.\<x>:

Do not use a trailing backslash. This would indicate the root directory of the drive. The following table shows some example drive strings.

You can also open a volume by referring to its volume name.  Volume handles may be opened as non-cached at the discretion of the file system, even when the non-cached option is not specified with CreateFile(). You should assume that all Microsoft file systems open volume handles as non-cached. The restrictions on non-cached I/O for files apply to volumes as well. A file system may or may not require buffer alignment even though the data is non-cached. However, if the non-cached option is specified when opening a volume, buffer alignment is enforced regardless of the file system on the volume. It is recommended on all file systems that you open volume handles as non-cached and follow the non-cached I/O restrictions.

Tape Drives

You can open tape drives using a file name of the form:  \\.\TAPE<x>. Where <x> is a number indicating which drive to open, starting with tape drive 0. To open tape drive 0 in an application written in C or C++, use the file name "\\\\.\\TAPE0". For Windows Me/98/95:  Opening tape drives is not supported.

Communications Resources

The CreateFile() function can create a handle to a communications resource, such as the serial portCOM1. For communications resources, the dwCreationDisposition parameter must be OPEN_EXISTING, and the hTemplate parameter must be NULL. Read, write, or read/write access can be specified, and the handle can be opened for overlapped I/O.

Consoles

The CreateFile() function can create a handle to console input (CONIN$). If the process has an open handle to it as a result of inheritance or duplication, it can also create a handle to the active screen buffer (CONOUT$). The calling process must be attached to an inherited console or one allocated by the AllocConsole() function. For console handles, set the CreateFile() parameters as follows.

The following list shows the effects of various settings of dwDesiredAccess and lpFileName.

Mailslots

If CreateFile() opens the client end of a mailslot, the function returns INVALID_HANDLE_VALUE if the mailslot client attempts to open a local mailslot before the mailslot server has created it with the CreateMailSlot() function.

Pipes

If CreateFile() opens the client end of a named pipe, the function uses any instance of the named pipe that is in the listening state. The opening process can duplicate the handle as many times as required but, once opened, the named pipe instance cannot be opened by another client. The access specified when a pipe is opened must be compatible with the access specified in the dwOpenMode parameter of the CreateNamedPipe() function.

ReadFile()

Parameters

hFile - [in] Handle to the file to be read. The file handle must have been created with the GENERIC_READ access right.

For asynchronous read operations, hFile can be any handle opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile() function, or a socket handle returned by the socket or accept function. Windows Me/98/95:  For asynchronous read operations, hFile can be a communications resource opened with the FILE_FLAG_OVERLAPPED flag by CreateFile(), or a socket handle returned by socket or accept. You cannot perform asynchronous read operations on mailslots, named pipes, or disk files.

lpBuffer - [out] Pointer to the buffer that receives the data read from the file.

nNumberOfBytesToRead - [in] Number of bytes to be read from the file.

lpNumberOfBytesRead - [out] Pointer to the variable that receives the number of bytes read.ReadFile() sets this value to zero before doing any work or error checking. If this parameter is zero when ReadFile() returns TRUE on a named pipe, the other end of the message-mode pipe called theWriteFile() function with nNumberOfBytesToWrite set to zero. If lpOverlapped is NULL,lpNumberOfBytesRead cannot be NULL. If lpOverlapped is not NULL, lpNumberOfBytesRead can be NULL. If this is an overlapped read operation, you can get the number of bytes read by calling GetOverlappedResult(). If hFile is associated with an I/O completion port, you can get the number of bytes read by callingGetQueuedCompletionStatus().

If I/O completion ports are used and you are using a callback routine to free the memory allocated to the OVERLAPPED structure pointed to by the lpOverlapped parameter, specify NULL as the value of this parameter to avoid a memory corruption problem during the de-allocation. This memory corruption problem will cause an invalid number of bytes to be returned in this parameter. For Windows Me/98/95:  This parameter cannot be NULL.

lpOverlapped - [in] Pointer to an OVERLAPPED structure. This structure is required if hFile was created withFILE_FLAG_OVERLAPPED.

If hFile was opened withFILE_FLAG_OVERLAPPED, the lpOverlapped parameter must not be NULL. It must point to a validOVERLAPPED structure. If hFile was created with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function can incorrectly report that the read operation is complete. If hFile was opened withFILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the read operation starts at the offset specified in theOVERLAPPED structure and ReadFile() may return before the read operation has been completed. In this case,ReadFile() returns FALSE and the GetLastError() function returns ERROR_IO_PENDING. This allows the calling process to continue while the read operation finishes. The event specified in the OVERLAPPED structure is set to the signaled state upon completion of the read operation. The caller must adjust the position of the file pointer upon completion. If hFile was not opened withFILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the read operation starts at the current file position andReadFile() does not return until the operation has been completed. The system updates the file pointer upon completion.

If hFile is not opened withFILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the read operation starts at the offset specified in theOVERLAPPED structure. ReadFile() does not return until the read operation has been completed. The system updates the file pointer upon completion. Windows 95/98/Me:  For operations on files, disks, pipes, or mailslots, this parameter must be NULL; a pointer to an OVERLAPPED structure causes the call to fail. However, you can perform overlapped I/O on serial and parallel ports.

Some Remarks

If part of the file is locked by another process and the read operation overlaps the locked portion, this function fails. An application must meet certain requirements when working with files opened with FILE_FLAG_NO_BUFFERING:

1. File access must begin at byte offsets within the file that are integer multiples of the volume's sector size. To determine a volume's sector size, call the GetDiskFreeSpace() function.

2. File access must be for numbers of bytes that are integer multiples of the volume's sector size. For example, if the sector size is 512 bytes, an application can request reads and writes of 512, 1024, or 2048 bytes, but not of 335, 981, or 7171 bytes.

3. Buffer addresses for read and write operations must be sector aligned (aligned on addresses in memory that are integer multiples of the volume's sector size). One way to sector align buffers is to use the VirtualAlloc() function to allocate the buffers. This function allocates memory that is aligned on addresses that are integer multiples of the system's page size. Because both page and volume sector sizes are powers of 2, memory aligned by multiples of the system's page size is also aligned by multiples of the volume's sector size.

Accessing the input buffer while a read operation is using the buffer may lead to corruption of the data read into that buffer. Applications must not read from, write to, reallocate, or free the input buffer that a read operation is using until the read operation completes. Characters can be read from the console input buffer by using ReadFile() with a handle to console input. The console mode determines the exact behavior of the ReadFile() function.If a named pipe is being read in message mode and the next message is longer than the nNumberOfBytesToRead parameter specifies,ReadFile() returns FALSE and GetLastError() returns ERROR_MORE_DATA. The remainder of the message may be read by a subsequent call to theReadFile() or PeekNamedPipe() function. When reading from a communications device, the behavior ofReadFile() is governed by the current communication time-outs as set and retrieved using the SetCommTimeouts() and GetCommTimeouts() functions. Unpredictable results can occur if you fail to set the time-out values. If ReadFile() attempts to read from a mailslot whose buffer is too small, the function returns FALSE and GetLastError() returns ERROR_INSUFFICIENT_BUFFER. If the anonymous write pipe handle has been closed andReadFile() attempts to read using the corresponding anonymous read pipe handle, the function returns FALSE and GetLastError() returns ERROR_BROKEN_PIPE. The ReadFile() function may fail and return ERROR_INVALID_USER_BUFFER orERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests. TheReadFile() code to check for the end-of-file condition (eof) differs for synchronous and asynchronous read operations. When a synchronous read operation reaches the end of a file, ReadFile() returns TRUE and sets *lpNumberOfBytesRead to zero. The following sample code tests for end-of-file for a synchronous read operation:

// Attempt a synchronous read operation.

bResult = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead, NULL) ;

// Check for end of file.

if (bResult &&  nBytesRead == 0, )

{

    // we're at the end of the file

}

An asynchronous read operation can encounter the end of a file during the initiating call to ReadFile(), or during subsequent asynchronous operation. If EOF is detected atReadFile() time for an asynchronous read operation, ReadFile() returns FALSE and GetLastError() returns ERROR_HANDLE_EOF. If EOF is detected during subsequent asynchronous operation, the call toGetOverlappedResult() to obtain the results of that operation returns FALSE andGetLastError() returns ERROR_HANDLE_EOF. To cancel all pending asynchronous I/O operations, use theCancelIo() function. This function only cancels operations issued by the calling thread for the specified file handle. I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED. If you are attempting to read from a floppy drive that does not have a floppy disk, the system displays a message box prompting the user to retry the operation. To prevent the system from displaying this message box, call the SetErrorMode() function with SEM_NOOPENFILEERRORBOX.  The following sample code illustrates testing for end-of-file for an asynchronous read operation:

// set up overlapped structure fields

gOverLapped.Offset     = 0;

gOverLapped.OffsetHigh = 0;

gOverLapped.hEvent     = hEvent;

// attempt an asynchronous read operation

bResult = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead, &gOverlapped);

// if there was a problem, or the async. operation's still pending...

if (!bResult)

{

    // deal with the error code

    switch (dwError = GetLastError())

    {

        case ERROR_HANDLE_EOF:

        {

            // we have reached the end of the file  during the call to ReadFile code to handle that

        }

        case ERROR_IO_PENDING:

        {

            // asynchronous i/o is still in progress do something else for a while

            GoDoSomethingElse();

            // check on the results of the asynchronous read

            bResult = GetOverlappedResult(hFile, &gOverlapped, &nBytesRead, FALSE);

            // if there was a problem...

            if (!bResult)

            {

                // deal with the error code

                switch (dwError = GetLastError())

                {

                    case ERROR_HANDLE_EOF:

                    {

                        // we have reached the end of the file during asynchronous operation

                    }

                    // deal with other error cases

                }   // end switch (dwError = GetLastError())

              }

        } // end case

        // deal with other error cases

    }// end  switch (dwError = GetLastError())

 } // end if

---------------------------------------------------Part 4/5-----------------------------------------------------

Further reading and digging:

1. Microsoft Visual C++, online MSDN.

2. Structure, enum, union and typedef story can be foundinC struct, enum, typedef etc.

3. For Multi-bytes, Unicode characters and Localization please refer toUnicode & Multibyte 1 (Story) andUnicode & Multibyte 2 (Implementation).

4. Check the best selling C / C++ and Windows books at Amazon.com.

| Previous |Main |Next |Site Index |Download |Disclaimer |Privacy |