Windows Process, thread and synchronization: Functions used in program examples of ModuleR, ModuleS, ModuleT, ModuleU, ModuleV and ModuleAA, wherever applicable.

To learn about function you can jump to Module 4.

Index

GetEnvironmentStrings()

GetEnvironmentVariable()

SetEnvironmentVariable()

GetEnvironmentStrings()

FreeEnvironmentStrings()

CreateWaitableTimer()

GetStdHandle()

CreatePipe()

DuplicateHandle()

GetCurrentProcess()

CreateFile()

ReadFile()

GetEnvironmentStrings()

Item	Description
Function	GetEnvironmentStrings().
Use	Retrieves the environment variables for the current process.
Prototype	LPVOID GetEnvironmentStrings(void);
Parameters	This function has no parameters.
Return value	If the function succeeds, the return value is a pointer to the environment block of the current process. If the function fails, the return value is NULL.
Include file	<windows.h>
Remark	Implemented as Unicode and ANSI versions. Note that Unicode support on Windows Me/98/95 requires Microsoft Layer for Unicode. The GetEnvironmentStrings() function returns a pointer to a block of memory that contains the environment variables of the calling process. Treat this memory as read-only; do not modify it directly. To add or change an environment variable, use the GetEnvironmentVariable() and SetEnvironmentVariable() functions. When the block returned by GetEnvironmentStrings() is no longer needed, it should be freed by calling the FreeEnvironmentStrings() function. Windows Me/98/95: GetEnvironmentStringsW() 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.
Table 1.

GetEnvironmentVariable()

Item	Description
Function	GetEnvironmentVariable().
Use	Retrieves the contents of the specified variable from the environment block of the calling process. The contents are in the form of a null-terminated string of characters.
Prototype	DWORD GetEnvironmentVariable( LPCTSTR lpName, LPTSTR lpBuffer, DWORD nSize);
Parameters	lpName [in] Pointer to a null-terminated string that specifies the name of the environment variable. lpBuffer [out] Pointer to a buffer that receives the contents of the specified environment variable. An environment variable has a maximum size limit of 32,767 characters, including the null-terminating character. nSize [in] Size of the buffer pointed to by the lpBuffer parameter, in bytes.
Return value	If the function succeeds, the return value is the number of bytes stored in the buffer pointed to by lpBuffer, not including the terminating null character. If lpBuffer is not large enough to hold the data, the return value is the buffer size, in bytes, required to hold the value string and its terminating null character. If the function fails, the return value is zero. If the specified environment variable was not found in the environment block, GetLastError() returns ERROR_ENVVAR_NOT_FOUND.
Include file	<windows.h>
Remark	Implemented as Unicode and ANSI versions. Note that Unicode support on Windows Me/98/95 requires Microsoft Layer for Unicode. Windows Me/98/95: GetEnvironmentVariableW() 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.
Table 2.

SetEnvironmentVariable()

Item	Description
Function	SetEnvironmentVariable().
Use	Sets the contents of the specified environment variable for the current process.
Prototype	BOOL SetEnvironmentVariable(LPCTSTR lpName, LPCTSTR lpValue);
Parameters	lpName [in] Pointer to a null-terminated string that specifies the name of the environment variable. The operating system creates the environment variable if it does not exist and lpValue is not NULL. lpValue [in] Pointer to a null-terminated string that specifies the contents of the environment variable. An environment variable has a maximum size limit of 32,767 characters, including the trailing null terminator. If this parameter is NULL, the variable is deleted from the current process's environment.
Return value	If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().
Include file	<windows.h>
Remark	Implemented as Unicode and ANSI versions. Note that Unicode support on Windows Me/98/95 requires Microsoft Layer for Unicode. This function has no effect on the system environment variables or the environment variables of other processes. Windows Me/98/95: SetEnvironmentVariableW() 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.
Table 3.

GetEnvironmentStrings()

Item	Description
Function	GetEnvironmentStrings().
Use	Retrieves the environment variables for the current process.
Prototype	LPVOID GetEnvironmentStrings(void);
Parameters	This function has no parameters.
Return value	If the function succeeds, the return value is a pointer to the environment block of the current process. If the function fails, the return value is NULL.
Include file	<windows.h>
Remark	Implemented as Unicode and ANSI versions. Note that Unicode support on Windows Me/98/95 requires Microsoft Layer for Unicode. The GetEnvironmentStrings() function returns a pointer to a block of memory that contains the environment variables of the calling process. Treat this memory as read-only; do not modify it directly. To add or change an environment variable, use the GetEnvironmentVariable() and SetEnvironmentVariable() functions. When the block returned by GetEnvironmentStrings() is no longer needed, it should be freed by calling the FreeEnvironmentStrings() function. Windows Me/98/95: GetEnvironmentStringsW() 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.
Table 4.

FreeEnvironmentStrings()

Item	Description
Function	FreeEnvironmentStrings().
Use	Frees a block of environment strings.
Prototype	BOOL FreeEnvironmentStrings(LPTSTR lpszEnvironmentBlock);
Parameters	lpszEnvironmentBlock [in] Pointer to a block of environment strings. The pointer to the block must be obtained by calling the GetEnvironmentStrings() function.
Return value	If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().
Include file	<windows.h>
Remark	Implemented as Unicode and ANSI versions. Note that Unicode support on Windows Me/98/95 requires Microsoft Layer for Unicode. Windows Me/98/95: FreeEnvironmentStringsW() 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.
Table 5.

CreateWaitableTimer()

Item	Description
Function	CreateWaitableTimer().
Use	Creates or opens a waitable timer object.
Prototype	HANDLE CreateWaitableTimer( LPSECURITY_ATTRIBUTES lpTimerAttributes, BOOL bManualReset, LPCTSTR lpTimerName);
Parameters	See below.
Return value	If the function succeeds, the return value is a handle to the timer object. If the named timer object exists before the function call, the function returns a handle to the existing object and GetLastError() returns ERROR_ALREADY_EXISTS. If the function fails, the return value is NULL. To get extended error information, call GetLastError().
Include file	<windows.h>
Remark	Implemented as Unicode and ANSI versions. Note that Unicode support on Windows Me/98/95 requires Microsoft Layer for Unicode. More remarks below.
Table 6.

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() returns ERROR_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.

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.

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

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

▪ 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()

Item	Description
Function	GetStdHandle().
Use	Retrieves a handle for the standard input, standard output, or standard error device.
Prototype	HANDLE GetStdHandle(DWORD nStdHandle);
Parameters	See below.
Return value	If the function succeeds, the return value is a handle to the specified device, or a redirected handle set by a previous call to SetStdHandle(). The handle has GENERIC_READ and GENERIC_WRITE access rights, unless the application has used SetStdHandle() to set a standard handle with lesser access. If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError(). If an application does not have associated standard handles, such as a service running on an interactive desktop, and has not redirected them, the return value is NULL.
Include file	<windows.h>
Remark	Handles returned by GetStdHandle() can be used by applications that need to read from or write to the console. When a console is created, the standard input handle is a handle to the console's input buffer, and the standard output and standard error handles are handles of the console's active screen buffer. These handles can be used by the ReadFile() and WriteFile() functions, or by any of the console functions that access the console input buffer or a screen buffer (for example, the ReadConsoleInput(), WriteConsole(), or GetConsoleScreenBufferInfo() functions). The standard handles of a process may be redirected by a call to SetStdHandle(), in which case GetStdHandle() returns the redirected handle. If the standard handles have been redirected, you can specify the CONIN$ value in a call to the CreateFile() function to get a handle to a console's input buffer. Similarly, you can specify the CONOUT$ value to get a handle to a console's active screen buffer.
Table 7.

Parameters

nStdHandle

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

Value	Meaning
STD_INPUT_HANDLE	Handle to the standard input device. Initially, this is a handle to the console input buffer, CONIN$.
STD_OUTPUT_HANDLE	Handle to the standard output device. Initially, this is a handle to the active console screen buffer, CONOUT$.
STD_ERROR_HANDLE	Handle to the standard error device. Initially, this is a handle to the active console screen buffer, CONOUT$.
Table 8

CreatePipe()

Item	Description
Function	CreatePipe().
Use	Creates an anonymous pipe, and returns handles to the read and write ends of the pipe.
Prototype	BOOL CreatePipe( PHANDLE hReadPipe, PHANDLE hWritePipe, LPSECURITY_ATTRIBUTES lpPipeAttributes, DWORD nSize);
Parameters	hReadPipe [out] Pointer to a variable that receives the read handle for the pipe. hWritePipe [out] Pointer to a variable that receives the write handle for the pipe. lpPipeAttributes [in] Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpPipeAttributes is NULL, the handle cannot be inherited. The lpSecurityDescriptor member of the structure specifies a security descriptor for the new pipe. If lpPipeAttributes is NULL, the pipe gets a default security descriptor. The ACLs in the default security descriptor for a pipe come from the primary or impersonation token of the creator. nSize [in] Size of the buffer for the pipe, in bytes. The size is only a suggestion; the system uses the value to calculate an appropriate buffering mechanism. If this parameter is zero, the system uses the default buffer size.
Return value	If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().
Include file	<windows.h>
Remark	CreatePipe() creates the pipe, assigning the specified pipe size to the storage buffer. CreatePipe() also creates handles that the process uses to read from and write to the buffer in subsequent calls to the ReadFile() and WriteFile() functions. To read from the pipe, a process uses the read handle in a call to the ReadFile() function. ReadFile() returns when one of the following is true: a write operation completes on the write end of the pipe, the number of bytes requested has been read, or an error occurs. When a process uses WriteFile() to write to an anonymous pipe, the write operation is not completed until all bytes are written. If the pipe buffer is full before all bytes are written, WriteFile() does not return until another process or thread uses ReadFile() to make more buffer space available. Anonymous pipes are implemented using a named pipe with a unique name. Therefore, you can often pass a handle to an anonymous pipe to a function that requires a handle to a named pipe.
Table 9.

DuplicateHandle()

Item	Description
Function	DuplicateHandle().
Use	Duplicates an object handle.
Prototype	BOOL DuplicateHandle( HANDLE hSourceProcessHandle, HANDLE hSourceHandle, HANDLE hTargetProcessHandle, LPHANDLE lpTargetHandle, DWORD dwDesiredAccess, BOOL bInheritHandle, DWORD dwOptions);
Parameters	See below.
Return value	If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().
Include file	<windows.h>
Remark	See below.
Table 10.

Parameters

hSourceProcessHandle

[in] Handle to the process with the handle to duplicate.

The handle must have the PROCESS_DUP_HANDLE access right.

hSourceHandle

[in] Handle to duplicate. This is an open object handle that is valid in the context of the source process. For a list of objects whose handles can be duplicated, see the following Remarks section.

hTargetProcessHandle

[in] Handle to the process that is to receive the duplicated handle. The handle must have the PROCESS_DUP_HANDLE access right.

lpTargetHandle

[out] Pointer to a variable that receives the duplicate handle. This handle value is valid in the context of the target process.

If hSourceHandle is a pseudo handle returned by GetCurrentProcess() or GetCurrentThread(), DuplicateHandle() converts it to a real handle to a process or thread, respectively.

If lpTargetHandle is NULL, the function duplicates the handle, but does not return the duplicate handle value to the caller. This behavior exists only for backward compatibility with previous versions of this function. You should not use this feature, as you will lose system resources until the target process terminates.

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.

Value	Meaning
DUPLICATE_CLOSE_SOURCE	Closes the source handle. This occurs regardless of any error status returned.
DUPLICATE_SAME_ACCESS	Ignores the dwDesiredAccess parameter. The duplicate handle has the same access as the source handle.
Table 11

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 use DuplicateHandle() 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, but DuplicateHandle() 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 the OpenProcess() 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.

Object	Description
Access token	The handle is returned by the CreateRestrictedToken(), DuplicateToken(), DuplicateTokenEx(), OpenProcessToken(), or OpenThreadToken() function.
Change notification	The handle is returned by the FindFirstChangeNotification() function.
Communications device	The handle is returned by the CreateFile() function.
Console input	The handle is returned by the CreateFile() function when CONIN$ is specified, or by the GetStdHandle() function when STD_INPUT_HANDLE is specified. Console handles can be duplicated for use only in the same process.
Console screen buffer	The handle is returned by the CreateFile() function when CONOUT$ is specified, or by the GetStdHandle() function when STD_OUTPUT_HANDLE is specified. Console handles can be duplicated for use only in the same process.
Desktop	The handle is returned by the GetThreadDesktop() function.
Event	The handle is returned by the CreateEvent() or OpenEvent() function.
File	The handle is returned by the CreateFile() function.
File mapping	The handle is returned by the CreateFileMapping() function.
Job	The handle is returned by the CreateJobObject() function.
Mailslot	The handle is returned by the CreateMailslot() function.
Mutex	The handle is returned by the CreateMutex() or OpenMutex() function.
Pipe	A named pipe handle is returned by the CreateNamedPipe() or CreateFile() function. An anonymous pipe handle is returned by the CreatePipe() function.
Process	The handle is returned by the CreateProcess(), GetCurrentProcess(), or OpenProcess() function.
Registry key	The handle is returned by the RegCreateKey(), RegCreateKeyEx(), RegOpenKey(), or RegOpenKeyEx() function. Note that registry key handles returned by the RegConnectRegistry() function cannot be used in a call to DuplicateHandle(). Windows Me/98/95: You cannot use DuplicateHandle to duplicate registry key handles.
Semaphore	The handle is returned by the CreateSemaphore() or OpenSemaphore() function.
Socket	The handle is returned by the socket or accept function.
Thread	The handle is returned by the CreateProcess(), CreateThread(), CreateRemoteThread(), or GetCurrentThread() function
Timer	The handle is returned by the CreateWaitableTimer() or OpenWaitableTimer() function.
Window station	The handle is returned by the GetProcessWindowStation() function.
Table 12

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:

▪ Desktop Security and Access Rights.

▪ File Security and Access Rights.

▪ File-Mapping Security and Access Rights.

▪ Job Object Security and Access Rights.

▪ Process Security and Access Rights.

▪ Registry Key Security and Access Rights.

▪ Synchronization Object Security and Access Rights.

▪