IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE IOCTL (nfpdev.h)
Il client invia ripetutamente la richiesta di IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE all'handle della sottoscrizione per ricevere messaggi sottoscritti durante l'arrivo. In genere, questo IOCTL verrà pennato nell'handle della sottoscrizione fino a quando non arriva effettivamente un messaggio corrispondente al tipo sottoscritto.
Codice principale
Buffer di input
Nessuno
Buffer di output
Al momento dell'arrivo, è necessario un buffer valido per restituire i dati del messaggio. Il primo DWORD di questo buffer è riservato per un hint al client per le dimensioni successive del buffer da restituire. Questo buffer in genere sarà 255 byte, ma il driver può richiedere che il client invii un buffer più grande fornendo solo l'hint e completando IOCTL con STATUS_BUFFER_OVERFLOW.
Blocco dello stato
Irp-IoStatus.Status> è impostato su STATUS_SUCCESS se la richiesta ha esito positivo.
In caso contrario, stato della condizione di errore appropriata come codice NTSTATUS.
Per altre informazioni, vedere Valori NTSTATUS.
Commenti
- Il client deve inviare un altro IOCTL ogni volta che viene completata la penna. Il driver DEVE usare blocchi appropriati per garantire che il numero di completamento di questo IOCTL equivale al numero di ricezione di messaggi riusciti per il tipo di sottoscrizione.
-
Di seguito sono riportate le azioni necessarie quando si usa questo IOCTL:
- Se questo IOCTL viene ricevuto in un handle non aperto in precedenza nello spazio dei nomi dei dispositivi "Subs\", il driver DEVE completarlo con STATUS_INVALID_DEVICE_STATE.
- Il driver deve mantenere una coda "Ricevuta" di messaggi ricevuti che corrispondono al tipo di sottoscrizione all'interno dell'handle del file di sottoscrizione.
-
Quando questo IOCTL viene ricevuto nel driver:
- Se la coda "Ricevuta" è vuota, il driver DEVE pennare L'IOCTL per il completamento successivo.
- Se la coda "Ricevuta" non è vuota, il driver DEVE dequeuerne un buffer di messaggi, copiare il buffer del messaggio nel buffer di output di IOCTL e completare immediatamente IOCTL con STATUS_SUCCESS.
- Se un messaggio corrispondente al tipo viene ricevuto e non viene attualmente pennato IOCTL, il driver DEVE aggiungere il buffer del messaggio alla coda "Ricevuta".
- Se viene ricevuto un messaggio corrispondente al tipo ed è disponibile un IOCTL con penna (la coda "Ricevuta" è vuota), il driver DEVE copiare il buffer del messaggio nel buffer di output di IOCTL e completare l'IRP con penna con STATUS_SUCCESS. La coda "Ricevuta" DEVE continuare a essere vuota dopo il completamento dell'IRP penna.
- Se il driver completa questo IOCTL con STATUS_SUCCESS, il primo DWORD [4 byte] del buffer di output DEVE contenere un hint per le dimensioni del buffer client successivo e il campo Informazioni IOCTL DEVE contenere le dimensioni di questo messaggio più sizeof(DWORD) (4 byte).
- Se IOCTL contiene un buffer di input, il driver DEVE completare IOCTL con STATUS_INVALID_PARAMETER.
- Se un messaggio ricevuto ha un payload a lunghezza zero, il driver DEVE ignorare il messaggio. Si tratta di un'ottimizzazione delle prestazioni perché i messaggi verranno eliminati con payload a lunghezza zero.
- Se un messaggio ricevuto è troppo grande da copiare nel buffer di IOCTL, il driver DEVE copiare le dimensioni del buffer necessarie nei primi 4 byte del buffer di output, impostare il campo "Information" di IOCTL su sizeof(DWORD) ("4") e completare IOCTL con STATUS_BUFFER_OVERFLOW. Il buffer dei messaggi deve essere lasciato nella coda "Ricevuta".
- Se questo IOCTL viene ricevuto mentre un altro viene attualmente pennato nell'handle della sottoscrizione, il secondo (o versione successiva) deve essere completato con STATUS_INVALID_DEVICE_STATE.
- Il driver DEVE supportare CancelIo della penna IOCTL.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 8 |
| Intestazione | nfpdev.h |