IOPCSyncIO::Read

Previous  Top  Next

HRESULT Read(
   [in] OPCDATASOURCE dwSource,
   [in] DWORD dwCount,
   [in, size_is(dwCount)] OPCHANDLE * phServer,
   [out, size_is(,dwCount)] OPCITEMSTATE ** ppItemValues,
   [out, size_is(,dwCount)] HRESULT ** ppErrors
   );

Descrizione
Questa funzione legge il valore delle informazioni quality e time per uno o più item in un gruppo. La funzione sarà eseguita fino al completamento prima di restituire i risultati. I dati possono essere letti da una CACHE o da un DEVICE.
Quando si legge da una CACHE, i dati sono validi solamente se sia il gruppo che l'item sono attivi. Se il gruppo o l'item sono inattivi, allora la Quality indicherà un cattivo funzionamento (OPC_QUALITY_OUT_OF_SERVICE).
I DEVICE letti non sono influenzati dallo stato ACTIVE di un gruppo o di un item.

Parametri	Descrizione
dwSource	Il 'data source'; OPC_DS_CACHE o OPC_DS_DEVICE
dwCount	Numero di item da leggere.
phServer	La lista dei server item handles per gli item da leggere
ppItemValues	Array di strutture in cui vengono ritornati i valori degli item.
ppErrors	Array di HRESULT indicanti il successo nella lettura di un singolo item. Gli errori corrispondono agli handles passati in phServer. Indica se la lettura ha avuto successo ottenendo un ben definito valore di quality e timestamp. Si noti che ogni error code FAILED indica che il corrispondente valore di Quality e Timestamp sono UNDEFINED.

Codici Restituiti

Codici Restituiti	Descrizione
S_OK	L'operazione ha avuto successo.
S_FALSE	L'operazione ha avuto successo ma ci sono uno o più errori in ppErrors.
E_FAIL	Operazione fallita.
E_OUTOFMEMORY	Memoria insufficiente.
E_INVALIDARG	Un argomento della funzione era non valido.

Codici Di Errore Restituiti

Codici Restituiti	Descrizione
S_OK	La lettura ha avuto successo.
E_FAIL	La lettura non ha avuto successo per questo item.
OPC_E_BADRIGHTS	L'item non è leggibile
OPC_E_INVALIDHANDLE	Item handle passato era non valido.
OPC_E_UNKNOWNITEMID	L'item non è più disponibile nello spazio di indirizzi del server.
S_xxx E_xxx	S_xxx – Possono essere fornite informazioni specifiche dal venditore se la quality di questo item è diversa da GOOD. E_xxx – Possono essere fornite informazioni specifiche sugli errori se non si può accedere a questo item. Questi specific codes possono essere passati attraverso il metodo GetErrorString().

Commenti
Se HRESULT è S_OK, allora ppError può essere ignorato (tutti i risultati sono garantiti dalla presenza di S_OK).
Se HRESULT è S_FALSE, allora ppError indicherà quale è lo stato di ciascun item letto.
Se HRESULT è un qualsiasi FAILED code allora il server dovrebbe tornare un puntatore nullo per tutti i parametri d'uscita incluso ppErrors.
Per ogni S_xxx ppError si assume che il corrispondente ITEMSTATE del client sia ben definito sebbene la Quality possa essere UNCERTAIN o BAD. Si raccomanda che chi vende il server fornisca informazioni addizionali riguardanti gli item UNCERTAIN o BAD.
Per ogni FAILED ppError code l'ITEMSTATE del client corrispondente si assume essere non definito. Infatti il Server deve settare il corrispondente ITEMSTATE VARIANT a VT_EMPTY così che possa essere ordinato in modo appropriato e il client possa eseguire una VariantClear su esso.
Si noti che un OPC_E_INVALIDHANDLE su uno degli item non avrà effetti sul processamento degli altri item ma causerà un HRESULT che ritorna S_FALSE.
Ci si aspetta che la lettura di una CACHE debba essere completata molto velocemente (in alcuni millisecondi). La lettura di un DEVICE può richiedere molto più tempo (molti secondi o più). La lettura di un DEVICE può richiedere l'esecuzione di altre operazioni sul server da parte di altri client.
Per questa ragione ci si aspetta che i client usino la lettura della CACHE nella maggior parte dei casi. La lettura dei DEVICE avviene solo in ben determinate circostanze quali i casi in cui si necessita una diagnostica dell'apparecchiatura.
Gli array ppItemValuese ppErrors sono allocati dal server ma devono essere liberati dal client.