Funzione CreateIoCompletionPort (ioapiset.h)
Crea una porta di completamento di input/output (I/O) e la associa a un handle di file specificato oppure crea una porta di completamento di I/O non ancora associata a un handle di file, consentendo l'associazione in un secondo momento.
L'associazione di un'istanza di un handle di file aperto a una porta di completamento di I/O consente a un processo di ricevere una notifica del completamento delle operazioni di I/O asincrone che coinvolgono tale handle di file.
Il termine handle di file usato qui fa riferimento a un'astrazione di sistema che rappresenta un endpoint di I/O sovrapposto, non solo un file su disco. Tutti gli oggetti di sistema che supportano operazioni di I/O sovrapposte, ad esempio endpoint di rete, socket TCP, pipe denominate e slot di posta elettronica, possono essere usati come handle di file. Per altre informazioni, vedere la sezione Osservazioni.
Sintassi
HANDLE CreateIoCompletionPort(
[in] HANDLE FileHandle,
[in, optional] HANDLE ExistingCompletionPort,
[in] ULONG_PTR CompletionKey,
[in] DWORD NumberOfConcurrentThreads
);
Parametri
[in] FileHandle
Handle di file aperto o INVALID_HANDLE_VALUE.
L'handle deve essere a un oggetto che supporta l'I/O sovrapposto.
Se viene fornito un handle, deve essere stato aperto per il completamento di I/O sovrapposto. Ad esempio, è necessario specificare il flag di FILE_FLAG_OVERLAPPED quando si usa la funzione CreateFile per ottenere l'handle.
Se viene specificato INVALID_HANDLE_VALUE , la funzione crea una porta di completamento di I/O senza associarla a un handle di file. In questo caso, il parametro ExistingCompletionPort deve essere NULL e il parametro CompletionKey viene ignorato.
[in, optional] ExistingCompletionPort
Handle per una porta di completamento di I/O esistente o NULL.
Se questo parametro specifica una porta di completamento I/O esistente, la funzione lo associa all'handle specificato dal parametro FileHandle . La funzione restituisce l'handle della porta di completamento I/O esistente se ha esito positivo; non crea una nuova porta di completamento di I/O.
Se questo parametro è NULL, la funzione crea una nuova porta di completamento di I/O e, se il parametro FileHandle è valido, lo associa alla nuova porta di completamento di I/O. In caso contrario, non si verifica alcuna associazione di handle di file. La funzione restituisce l'handle alla nuova porta di completamento di I/O, se riuscita.
[in] CompletionKey
Chiave di completamento definita dall'utente inclusa in ogni pacchetto di completamento di I/O per l'handle di file specificato. Per altre informazioni, vedere la sezione Osservazioni.
[in] NumberOfConcurrentThreads
Numero massimo di thread che il sistema operativo può consentire di elaborare simultaneamente pacchetti di completamento di I/O per la porta di completamento di I/O. Questo parametro viene ignorato se il parametro ExistingCompletionPort non è NULL.
Se questo parametro è zero, il sistema consente il numero di thread in esecuzione simultanei come sono presenti processori nel sistema.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è l'handle di una porta di completamento di I/O:
- Se il parametro ExistingCompletionPort era NULL, il valore restituito è un nuovo handle.
- Se il parametro ExistingCompletionPort è un handle di porta di completamento di I/O valido, il valore restituito è lo stesso handle.
- Se il parametro FileHandle era un handle valido, tale handle di file è ora associato alla porta di completamento di I/O restituita.
Commenti
Il sistema di I/O può essere indicato per inviare pacchetti di notifica di completamento di I/O alle porte di completamento di I/O, in cui vengono accodati. La funzione CreateIoCompletionPort fornisce questa funzionalità.
Una porta di completamento di I/O e il relativo handle sono associati al processo che lo ha creato e non è condivisibile tra processi. Tuttavia, un singolo handle è condivisibile tra thread nello stesso processo.
CreateIoCompletionPort può essere usato in tre modalità distinte:
- Creare solo una porta di completamento di I/O senza associarla a un handle di file.
- Associare una porta di completamento di I/O esistente a un handle di file.
- Eseguire sia la creazione che l'associazione in una singola chiamata.
L'handle passato nel parametro FileHandle può essere qualsiasi handle che supporta l'I/O sovrapposto. In genere, si tratta di un handle aperto dalla funzione CreateFile usando il flag FILE_FLAG_OVERLAPPED (ad esempio file, slot di posta elettronica e pipe). Gli oggetti creati da altre funzioni, ad esempio socket , possono essere associati anche a una porta di completamento di I/O. Per un esempio che usa socket, vedere AcceptEx. Un handle può essere associato a una sola porta di completamento di I/O e dopo aver effettuato l'associazione, l'handle rimane associato alla porta di completamento di I/O finché non viene chiusa.
Per altre informazioni sulla teoria della porta di completamento di I/O, sull'utilizzo e sulle funzioni associate, vedere Porte di completamento I/O.
Più handle di file possono essere associati a una singola porta di completamento di I/O chiamando CreateIoCompletionPort più volte con lo stesso handle di porta di completamento I/O nel parametro ExistingCompletionPort e un handle di file diverso nel parametro FileHandle ogni volta.
Usare il parametro CompletionKey per consentire all'applicazione di tenere traccia delle operazioni di I/O completate. Questo valore non viene usato da CreateIoCompletionPort per il controllo funzionale; invece, è collegato all'handle di file specificato nel parametro FileHandle al momento dell'associazione con una porta di completamento di I/O. Questa chiave di completamento deve essere univoca per ogni handle di file e accompagna l'handle di file durante il processo di accodamento interno. Viene restituito nella funzione GetQueuedCompletionStatus quando arriva un pacchetto di completamento. Il parametro CompletionKey viene usato anche dalla funzione PostQueuedCompletionStatus per accodare i propri pacchetti di completamento a scopo speciale.
Dopo che un'istanza di un handle aperto è associata a una porta di completamento di I/O, non può essere usata nella funzione ReadFileEx o WriteFileEx perché queste funzioni dispongono di meccanismi di I/O asincroni.
È consigliabile non condividere un handle di file associato a una porta di completamento di I/O usando l'ereditarietà dell'handle o una chiamata alla funzione DuplicateHandle . Le operazioni eseguite con tali handle duplicati generano notifiche di completamento. È consigliabile prendere in considerazione attentamente.
L'handle della porta di completamento I/O e ogni handle di file associato a quella determinata porta di completamento di I/O sono noti come riferimenti alla porta di completamento di I/O. La porta di completamento di I/O viene rilasciata quando non sono presenti altri riferimenti. Pertanto, tutti questi handle devono essere chiusi correttamente per rilasciare la porta di completamento di I/O e le relative risorse di sistema associate. Dopo aver soddisfatto queste condizioni, chiudere l'handle della porta di completamento I/O chiamando la funzione CloseHandle .
In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.
| Tecnologia | Supportato |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| Failover trasparente SMB 3.0 (TFO) | Sì |
| SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) | Sì |
| File system del volume condiviso del cluster (CsvFS) | Sì |
| File system resiliente (ReFS) | Sì |
Requisiti
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | ioapiset.h (includere Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |
Vedere anche
Funzioni
Argomenti generali