IOPCAsyncIO2::Read

Previous  Top  Next

HRESULT Read(
   [in] DWORD dwCount,
   [in, size_is(dwCount)] OPCHANDLE * phServer,
   [in] DWORD dwTransactionID,
   [out] DWORD *pdwCancelID,
   [out, size_is(,dwCount)] HRESULT ** ppErrors
   );

Descrizione
Legge uno o più item da un gruppo. Il risultato è ritornato attraverso una connessione all'interfaccia IOPCDataCallback del client stabilita attraverso l'interfaccia IConnectionPointContainer del server.
Le letture avvengono da un DEVICE e non sono influenzate dallo stato ACTIVE del group o dell'item.

Parametri	Descrizione
dwCount	Numero di item da leggere.
phServer	Array di server item handles degli item da leggere.
dwTransactionID	Transaction ID generata dal client. Questo è inclusa nell'informazione di completamento fornita all'OnReadComplete.
pdwCancelID	Punto per ritornare l'ID generato dal server da essere usato nei casi in cui l'operazione deve essere cancellata.
ppErrors	Array di errori per ciascun item ritornato dal server.

Codici Restituiti

Codici Restituiti	Descrizione
S_OK	L'operazione ha avuto successo. La lettura è stata iniziata con successo.
E_FAIL	L'operazione non ha avuto successo.
E_OUTOFMEMORY	Memoria insufficiente.
E_INVALIDARG	Un argomento della funzione era non valido.
S_FALSE	Uno o più degli item passati non possono essere letti. L'array ppError indica quali degli item contenuti nel phServer non possono essere letti. Ogni item che non ritorna un errore qui verrà letto e i risultati sarranno ritornati all'interfaccia OnReadComplete. Gli item che danno errori non saranno ritornati nella callback.
CONNECT_E_NOCONNECTION	Il client non ha registrato una callback attraverso la IConnectionPoint::Advise.

Codici Di Errore Restituiti

Codici Restituiti	Descrizione
S_OK	Il corrispondente item handle era valido e l'item information sarà ritornata attraverso OnReadComplete.
E_FAIL	La lettura non è avvenuta per questo item.
OPC_E_BADRIGHTS	L'item non è leggibile.
OPC_E_INVALIDHANDLE	L'item handle passato era non valido.
OPC_E_UNKNOWNITEMID	L'item non è più disponibile nello spazio di indirizzi del server.
E_xxx S_xxx	Possono anche essere ritornati errori specifici per ogni fornitore. Informazioni descrittive per tali errori possono essere ottenuti da un GetErrorString.

Commenti
Alcuni server possono ritornare errori molto più frequentemente di altri che accodano semplicemente le richieste con un controllo minimo nella callback. Il client dovrebbe essere pronto a trattare con essi.
Se l'HRESULT è S_OK, allora il vettore ppError può essere ignorato (tuttti i risultati saranno garantiti dalla presenza di S_OK).
Se HRESULT contiene qualche FAILED code allora il server dovrebbe restituire un puntatore nullo per tutti i parametri d'uscita. Si noti che in questo caso non avverrà alcuna Callback.
Se tutti gli errori nel vettore ppError sono failure codes allora nessuna callback ne prenderà il posto.
Gli Item per i quali il ppError ritorna un success code ritorneranno in una callback OnReadComplete. Si noti che gli errori ritornati nella callback possono differire da quelli ritornati dalla Read.
Il server deve ritornare tutti i risultati in una singola callback. Cioè, se gli item nel gruppo richiedono più transazioni a uno o più device fisici allora il server deve aspettare fino a quando ognuna di queste sia completa prima di invocare la procedura OnReadComplete.
Il client deve liberare l'array ppError restituito.