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 i messaggi sottoscritti man mano che arrivano. In genere, questo IOCTL verrà inserito 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
È necessario un buffer valido per la restituzione dei dati del messaggio all'arrivo. 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à di 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 di 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.
Osservazioni
- 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 completamenti riusciti di questo IOCTL equivalgono al numero di ricevimenti dei messaggi riusciti per il tipo di sottoscrizione.
-
Quando si usa questo IOCTL, sono necessarie le azioni seguenti:
- Se questo IOCTL viene ricevuto su un handle non aperto in precedenza nello spazio dei nomi del dispositivo "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 eseguire la penna IOCTL per il completamento successivo.
- Se la coda "Ricevuta" non è vuota, il driver DEVE annullare la coda di un buffer di messaggi, copiare il buffer dei messaggi nel buffer di output di IOCTL e completare immediatamente l'IOCTL con STATUS_SUCCESS.
- Se viene ricevuto un messaggio corrispondente al tipo e non viene eseguito alcun input penna IOCTL, il driver DEVE aggiungere il buffer dei messaggi 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 dei messaggi 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 con 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 del 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 di lunghezza zero, il driver DEVE ignorare il messaggio. Si tratta di un'ottimizzazione delle prestazioni perché Windows elimina i messaggi con payload di lunghezza zero.
- Se un messaggio ricevuto è troppo grande da copiare nel buffer di questo 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 oggetto è attualmente inserito nell'handle della sottoscrizione, il secondo (o versione successiva) deve essere completato con STATUS_INVALID_DEVICE_STATE.
- Il driver DEVE supportare CancelIo dell'IOCTL pended.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows 8 |
| intestazione | nfpdev.h |
Vedere anche
guida di progettazione generale NFC (Near Field Communication)