IOPCAsyncIO2::Write

Previous  Top  Next

HRESULT Write(
   [in] DWORD dwCount,
   [in, size_is(dwCount)] OPCHANDLE * phServer,
   [in, size_is(dwCount)] VARIANT * pItemValues,
   [in] DWORD dwTransactionID,
   [out] DWORD *pdwCancelID,
   [out, size_is(,dwCount)] HRESULT ** ppErrors
   );
Descrizione
Scrive uno o più item in un gruppo. Il risultato è ritornato attraverso una connessione all'interfaccia IOPCDataCallback del client stabilita attraverso l'IConnectionPointContainer del server.

Parametri	Descrizione
dwCount	Numero di item da scrivere.
phServer	Array di server item handles degli item da scrivere.
pItemValues	Lista di valori da scrivere. Non si richiede il data types dei valori non deve necessariamnte essere uguale a quello richiesto o a quello canonico ma è necessario che questo sia convertibile in un tipo canonico.
dwTransactionID	Transaction ID generata dal client. Questo è inclusa nell'informazione di completamento fornita all'OnWriteComplete.
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

Return Code	Descrizione
S_OK	L'operazione ha avuto 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 scritti. L'array ppError indica quali degli item contenuti nel phServer non possono essere scritti. Ogni item che non ritorna un errore qui verrà scritto e i risultati sarranno ritornati all'interfaccia OnWriteComplete. 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 OnWriteComplete.
E_FAIL	La scrittura non è avvenuta per questo item.
OPC_E_BADRIGHTS	L'item non è scrivibile.
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 OnWriteComplete. Si noti che gli errori ritornati nella callback possono differire da quelli ritornati dalla write.
Il server deve ritornare tutti i risultati in una singola callback. Cioè, se gli item nel gruppo richiedono più transazioni fisiche a uno o più device fisici allora il server deve aspettare fino a quando ognuna di queste sia completa prima di invocare la callback.
Il client deve liberare l'array ppError restituitogli.