AllocateUserPhysicalPages-Funktion (memoryapi.h)

Artikel
03/01/2024

Ordnet physische Speicherseiten zu, die innerhalb eines AWE-Bereichs ( Address Windowing Extensions ) eines angegebenen Prozesses zugeordnet und aufgehoben werden sollen.

64-Bit-Windows auf Itanium-basierten Systemen: Aufgrund der unterschiedlichen Seitengrößen wird AllocateUserPhysicalPages für 32-Bit-Anwendungen nicht unterstützt.

Syntax

BOOL AllocateUserPhysicalPages(
  [in]      HANDLE     hProcess,
  [in, out] PULONG_PTR NumberOfPages,
  [out]     PULONG_PTR PageArray
);

Parameter

[in] hProcess

Ein Handle für einen Prozess.

Die Funktion weist Arbeitsspeicher zu, der später im virtuellen Adressraum dieses Prozesses zugeordnet werden kann. Das Handle muss über das zugriffsrecht PROCESS_VM_OPERATION verfügen. Weitere Informationen finden Sie unter Prozesssicherheit und Zugriffsrechte.

[in, out] NumberOfPages

Die Größe des zu zuordnenden physischen Arbeitsspeichers in Seiten.

Verwenden Sie die GetSystemInfo-Funktion , um die Seitengröße des Computers zu bestimmen. Bei der Ausgabe empfängt dieser Parameter die Anzahl der tatsächlich zugeordneten Seiten, die möglicherweise kleiner als die angeforderte Zahl sein kann.

[out] PageArray

Ein Zeiger auf ein Array zum Speichern der Seitenrahmennummern des zugeordneten Arbeitsspeichers.

Die Größe des zugeordneten Arrays sollte mindestens die NumberOfPages mal die Größe des ULONG_PTR Datentyps sein.

Versuchen Sie nicht, diesen Puffer zu ändern. Es enthält Betriebssystemdaten, und eine Beschädigung kann katastrophal sein. Die Informationen im Puffer sind für eine Anwendung nicht nützlich.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert TRUE.

Es können weniger Seiten als angefordert zugeordnet werden. Der Aufrufer muss den Wert des Parameters NumberOfPages bei der Rückgabe überprüfen, um zu ermitteln, wie viele Seiten zugeordnet sind. Alle zugeordneten Seitenrahmennummern werden sequenziell im Speicher platziert, auf den der UserPfnArray-Parameter verweist.

Wenn die Funktion fehlschlägt, ist der Rückgabewert FALSE, und es werden keine Frames zugeordnet. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die Funktion AllocateUserPhysicalPages wird verwendet, um physischen Arbeitsspeicher zuzuweisen, der später im virtuellen Adressraum des Prozesses zugeordnet werden kann. Das SeLockMemoryPrivilege-Recht muss im Token des Aufrufers aktiviert sein, andernfalls schlägt die Funktion mit ERROR_PRIVILEGE_NOT_HELD fehl. Weitere Informationen finden Sie unter Berechtigungskonstanten.

Der von dieser Funktion zugewiesene Arbeitsspeicher muss physisch im System vorhanden sein. Nachdem der Arbeitsspeicher zugewiesen wurde, ist er gesperrt und für den Rest des virtuellen Speicherverwaltungssystems nicht mehr verfügbar.

Physische Seiten können nicht gleichzeitig an mehr als einer virtuellen Adresse zugeordnet werden.

Physische Seiten können sich an jeder physischen Adresse befinden. Sie sollten keine Annahmen über die Kontinuität der physischen Seiten machen.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie das _WIN32_WINNT Makro als 0x0500 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

AllocateUserPhysicalPages2, das dem SDK in einer späteren Version hinzugefügt wurde, ist identisch mit AllocateUserPhysicalPages , fügt jedoch die Parameter ExtendedParameters und ExtendedParameterCount hinzu.

Beispiele

Ein Beispiel finden Sie unter AWE-Beispiel.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	memoryapi.h (einschließlich Windows.h, Memoryapi.h)
Bibliothek	onecore.lib
DLL	Kernel32.dll