IOPCServer::AddGroup

Previous  Top  Next

HRESULT AddGroup(
   [in, string] LPCWSTR szName,
   [in] BOOL bActive,
   [in] DWORD dwRequestedUpdateRate,
   [in] OPCHANDLE hClientGroup,
   [unique, in] LONG *pTimeBias,
   [in] FLOAT * pPercentDeadband,
   [in] DWORD dwLCID,
   [out] OPCHANDLE * phServerGroup,
   [out] DWORD *pRevisedUpdateRate,
   [in] REFIID riid,
   [out, iid_is(riid)] LPUNKNOWN * ppUnk
   );

Descrizione
Aggiunge un Group al Server.

Parametri	Descrizione
SzName	Nome del group. Il nome deve essere unico fra gli altri groups creati da questo client. Se nessun nome è dato ([szName] punta a una stinga NUL ) il server genererà un nome unico. Il nome generato dal server sarà anche unico relativamente a qualunque altro group pubblico esistente.
Bactive	FALSE se il Gruppo è creato come inattivo. TRUE se il Gruppo è creato come attivo.
DwRequestedUpdateRate	Il Client specifica la frequenza più alta alla quale i cambiamenti dei dati possono essere spediti a OnDataChange per items di questo group. Questo indica anche l'accuratezza desiderata dei dati contenuti nella cache . Questo è volto solo a controllare il comportamento dell'interfaccia. Come il server tratta l'aggiornamento della frequenza e quanto spesso interroga in maniera ciclica l'hardware è un dettaglio che riguarda la realizzazione. Il passare 0 indica al server che dovrebbe usare la più alta frequenza praticabile. La frequenza è specificata in millisecondi.
HClientGroup	Sistema di identificazione fornito al client per questo group. [riferisciti alla descrizione dei tipi di dati, parametri, e strutture per più informazioni su questo parametro]
PTimeBias	Puntatore a un Long contenente il TimeBias iniziale (in minuti) per il Group. Passa un puntatore a NULL se si desidera che il group usi il TimeBias di default del sistema. Questo bias si comporta come il campo Bias della struttura Win32 TIME_ZONE_INFORMATION .
PPercentDeadband	La variazione percentuale di un item che causa,per quel valore, una callback al client. Questo parametro si riferisce solo a item nel group che hanno dwEUType di tipo Analog. Un puntatore NULL è equivalente a 0.0.
DwLCID	La lingua che deve essere utilizzata dal server quando ritorna valori tipo testo per operazioni su questo group. Ciò potrebbe includere allarmi o condizioni dello stato del sistema o dei contatti digitali.
PhServerGroup	Luogo dove il server immagazzina l'identificatore unico relativo al group creato di recente. Il cliente userà l'identificatore che il server gli ha fornito per molte delle funzioni seguenti che il client richiede al server di compiere sul group.

pRevisedUpdateRate	Il server ritorna il valore che attualmente usa per l'UpdateRate, il quale può differire dal RequestedUpdateRate. Nota che questo può essere anche più lento rispetto alla frequenza alla quale il server internamente ottiene i dati ed aggiorna la cache.In generale il server deve "round up" la frequenza richiesta alla frequenza più prossima supportata e disponibile. La frequenza è specificata in millisecondi.Il server ritorna HRESULT di OPC_S_UNSUPPORTEDRATE quando ritorna un valore in revisedUpdateRate che è diverso da RequestedUpdateRate.
riid	Il tipo di interfaccia desiderata (e.g. IID_IOPCItemMgt)
ppUnk	Dove immagazzinare il puntatore all'interfaccia restituito NULL è restituito per oqni FAILED HRESULT.

Codici restituiti

Codici restituiti	Descrizione
S_OK	L'operazione ha avuto successo.
E_FAIL	L'operazione ha fallito.
E_OUTOFMEMORY	Non c'è memoria a sufficienza
E_INVALIDARG	Un argomento della funzione era invalido
OPC_E_DUPLICATENAME	Nome duplicato non valido.
OPC_S_UNSUPPORTEDRATE	Il server non supporta la frequenza richiesta.Viene restituita la frequenza che il server riesce a supportare.
E_NOINTERFACE	L'interfaccia(riid) richiesta non è supportata dal server.

Comportamento
Un Group è un contenitore logico che permette ad un client di organizzare e gestire gli items.Il server creerà un oggetto group, e restituirà un puntatore all'interfaccia richiesta dal client. Se il client richiede una interfaccia opzionale che il server non supporta, il server deve restituire un errore indicante che l'interfaccia non è supportata.
La frequenza richiesta/frequenza fornita dovrebbe essere deterministica nella sessione client/ server cioè il client si aspetta che per la stessa configurazione del server, l'aggiunta di un group con una certa frequenza di aggiornamento, non avrà alcuna conseguenza sulla RevisedRate, indipendentemente dal numero di client e item che sono stati aggiunti.

Commenti
Il comportamento atteso del tempo di vita dell'oggetto è il seguente:
anche se tutte le interfacce vengono rilasciate, il group non sarà cancellato fino a quando non viene invocato RemoveGroup . Un modo per il server di far ciò è assegnare al group un conteggio di riferimento iniziale di 2; uno per 'Add' ed uno per l'Interfaccia che è stata creata.
Il cliente non dovrebbe chiamare RemoveGroup senza rilasciare prima tutte le interfacce. Il client non dovrebbe rilasciare neanche il server senza rimuovere prima tutti i group privati.
Poiché il server è il 'container' per i groups,gli è permesso rimuovere di forza tutti i groups rimasti nel momento in cui tutte le interfacce del server sono state rilasciate.
Il livello di localizzazione supportato(dwLCID) è interamente dipendente dal server. I server che non supportano la localizzazione dinamica possono ignorare questo parametro.
Vedi pure la funzione MoveToPublicper maggiori informazioni sui groups pubblici.
Il TimeBias di default per il group sarà quello del sistema nel quale il group è stato creato