Metodo IOleObject::D oVerb (oleidl.h)

Articolo
03/13/2024

Richiede che un oggetto esegua un'azione in risposta a un'azione dell'utente finale. Le azioni possibili vengono enumerate per l'oggetto in IOleObject::EnumVerbs.

Sintassi

HRESULT DoVerb(
  [in] LONG           iVerb,
  [in] LPMSG          lpmsg,
  [in] IOleClientSite *pActiveSite,
  [in] LONG           lindex,
  [in] HWND           hwndParent,
  [in] LPCRECT        lprcPosRect
);

Parametri

[in] iVerb

Numero assegnato al verbo nella struttura OLEVERB restituito da IOleObject::EnumVerbs.

[in] lpmsg

Puntatore alla struttura MSG che descrive l'evento ,ad esempio un doppio clic, che ha richiamato il verbo. Il chiamante deve passare la struttura MSG non modificata, senza tentare di interpretare o modificare i valori di uno dei membri della struttura.

[in] pActiveSite

Puntatore all'interfaccia IOleClientSite nel sito client attivo dell'oggetto, in cui si è verificato l'evento che ha richiamato il verbo.

[in] lindex

Questo parametro è riservato e deve essere zero.

[in] hwndParent

Punto di controllo della finestra del documento contenente l'oggetto. Questo e lprcPosRect insieme consentono di aprire una finestra temporanea per un oggetto, dove hwndParent è la finestra padre in cui deve essere visualizzata la finestra dell'oggetto e lprcPosRect definisce l'area disponibile per la visualizzazione della finestra dell'oggetto all'interno di tale padre. Una finestra temporanea è utile, ad esempio, a un oggetto multimediale che si apre per la riproduzione ma non per la modifica.

[in] lprcPosRect

Puntatore alla struttura RECT contenente le coordinate, in pixel, che definiscono il rettangolo di delimitazione di un oggetto in hwndParent. Questo e hwndParent insieme consentono di aprire oggetti multimediali per la riproduzione, ma non per la modifica.

Valore restituito

Questo metodo restituisce S_OK se l'operazione ha esito positivo. Gli altri valori restituiti possibili includono i seguenti:

Codice restituito	Descrizione
OLE_E_NOT_INPLACEACTIVE	iVerb impostato su OLEIVERB_UIACTIVATE o OLEIVERB_INPLACEACTIVATE e l'oggetto non è già visibile.
OLE_E_CANT_BINDTOSOURCE	Il gestore dell'oggetto o l'oggetto collegamento non può connettersi all'origine del collegamento.
DV_E_LINDEX	Lindex non valido.
OLEOBJ_S_CANNOT_DOVERB_NOW	Il verbo è valido, ma nello stato corrente dell'oggetto non può eseguire l'azione corrispondente.
OLEOBJ_S_INVALIDHWND	DoVerb ha avuto esito positivo, ma hwndParent non è valido.
OLEOBJ_E_NOVERBS	L'oggetto non supporta verbi.
OLEOBJ_S_INVALIDVERB	L'origine del collegamento si trova in una rete che non è connessa a un'unità nel computer.
MK_E_CONNECT	L'origine del collegamento si trova in una rete che non è connessa a un'unità nel computer.
OLE_E_CLASSDIFF	La classe per l'origine del collegamento è stata sottoposta a una conversione.
E_NOTIMPL	L'oggetto non supporta l'attivazione sul posto o non riconosce un numero di verbo negativo.

Commenti

Un "verbo" è un'azione eseguita da un oggetto OLE in risposta a un messaggio dal relativo contenitore. Il contenitore di un oggetto o un client collegato all'oggetto chiama in genere IOleObject::D oVerb in risposta a un'azione dell'utente finale, ad esempio facendo doppio clic sull'oggetto. Le varie azioni disponibili per un determinato oggetto vengono enumerate in una struttura OLEVERB , che il contenitore ottiene chiamando IOleObject::EnumVerbs. IOleObject::D oVerb corrisponde al valore di iVerb rispetto al membro iVerb della struttura per determinare il verbo da richiamare.

Tramite IOleObject::EnumVerbs, un oggetto, anziché il relativo contenitore, determina quali verbi (ad esempio azioni) supporta. OLE 2 definisce sette verbi disponibili, ma non necessariamente utili, per tutti gli oggetti. Inoltre, ogni oggetto può definire verbi aggiuntivi univoci. Nella tabella seguente vengono descritti i verbi definiti da OLE.

Verbo	Descrizione
OLEIVERB_PRIMARY (0L)	Specifica l'azione che si verifica quando un utente finale fa doppio clic sull'oggetto nel relativo contenitore. L'oggetto, non il contenitore, determina questa azione. Se l'oggetto supporta l'attivazione sul posto, il verbo primario attiva in genere l'oggetto sul posto.
OLEIVERB_SHOW (-1)	Indica a un oggetto di visualizzare se stesso per la modifica o la visualizzazione. Chiamato per visualizzare gli oggetti appena inseriti per la modifica iniziale e per visualizzare le origini di collegamento. In genere un alias per un altro verbo definito dall'oggetto.
OLEIVERB_OPEN (-2)	Indica a un oggetto, incluso quello che supporta in caso contrario l'attivazione sul posto, di aprire se stesso per la modifica in una finestra separata da quella del relativo contenitore. Se l'oggetto non supporta l'attivazione sul posto, questo verbo ha la stessa semantica di OLEIVERB_SHOW.
OLEIVERB_HIDE (-3)	Determina la rimozione dell'interfaccia utente da parte di un oggetto dalla visualizzazione. Si applica solo agli oggetti attivati sul posto.
OLEIVERB_UIACTIVATE (-4)	Attiva un oggetto sul posto, insieme al set completo di strumenti dell'interfaccia utente, inclusi menu, barre degli strumenti e il relativo nome nella barra del titolo della finestra del contenitore. Se l'oggetto non supporta l'attivazione sul posto, deve restituire E_NOTIMPL.
OLEIVERB_INPLACEACTIVATE (-5)	Attiva un oggetto sul posto senza visualizzare strumenti, ad esempio menu e barre degli strumenti, che gli utenti finali devono modificare il comportamento o l'aspetto dell'oggetto. Facendo clic su un singolo oggetto di questo tipo, viene negoziata la visualizzazione degli strumenti dell'interfaccia utente con il relativo contenitore. Se il contenitore rifiuta, l'oggetto rimane attivo ma senza gli strumenti visualizzati.
OLEIVERB_DISCARDUNDOSTATE (-6)	Usato per indicare agli oggetti di rimuovere qualsiasi stato di annullamento che potrebbero essere gestiti senza disattivare l'oggetto.

Note ai chiamanti

I contenitori chiamano IOleObject::D oVerb come parte dell'inizializzazione di un oggetto appena creato. Prima di effettuare la chiamata, i contenitori devono prima chiamare IOleObject::SetClientSite per informare l'oggetto della relativa posizione di visualizzazione e IOleObject::SetHostNames per avvisare l'oggetto che si tratta di un oggetto incorporato e attivare le modifiche appropriate all'interfaccia utente dell'applicazione oggetto in preparazione all'apertura di una finestra di modifica.

IOleObject::D oVerb esegue automaticamente l'applicazione server OLE. Se si verifica un errore durante l'esecuzione del verbo, l'applicazione oggetto viene arrestata.

Se un utente finale richiama un verbo con un significato diverso dalla selezione di un comando da un menu (ad esempio, facendo doppio clic o, più raramente, facendo clic su un oggetto), il contenitore dell'oggetto deve passare un puntatore a una struttura MSG di Windows contenente il messaggio appropriato. Ad esempio, se l'utente finale richiama un verbo facendo doppio clic sull'oggetto, il contenitore deve passare una struttura MSG contenente WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK o WM_RBUTTONDBLCLK. Se il contenitore non passa alcun messaggio, lpmsg deve essere impostato su NULL. L'oggetto deve ignorare il membro hwnd della struttura MSG passata, ma può usare tutti gli altri membri MSG.

Se il contenitore di incorporamento dell'oggetto chiama IOleObject::D oVerb, il puntatore del sito client (pClientSite) passato a IOleObject::D oVerb corrisponde a quello del sito di incorporamento. Se l'oggetto incorporato è un'origine di collegamento, il puntatore passato a IOleObject::D oVerb è quello del sito client del client di collegamento.

Quando IOleObject::D oVerb viene richiamato su un collegamento OLE, può restituire OLE_E_CLASSDIFF o MK_CONNECTMANUALLY. L'oggetto collegamento restituisce l'errore precedente quando l'origine del collegamento è stata sottoposta a una sorta di conversione mentre il collegamento era passivo. L'oggetto collegamento restituisce quest'ultimo errore quando l'origine del collegamento si trova in un'unità di rete che non è attualmente connessa al computer del chiamante. L'unico modo per connettere un collegamento in queste condizioni consiste nel chiamare IUnknown::QueryInterface, richiedere IOleLink, allocare un contesto di associazione ed eseguire l'origine del collegamento chiamando IOleLink::BindToSource.

Le applicazioni contenitore che non supportano l'attivazione sul posto generale possono comunque usare i parametri hwndParent e lprcPosRect per supportare la riproduzione sul posto dei file multimediali. I contenitori devono passare parametri hwndParent e lprcPosRect validi a IOleObject::D oVerb.

Alcuni esempi di codice passano un valore lindex pari a -1 anziché zero. Il valore -1 funziona, ma deve essere evitato a favore di zero. Il parametro lindex è un parametro riservato e per motivi di coerenza Microsoft consiglia di assegnare un valore zero a tutti i parametri riservati.

Note per gli implementatori

Oltre ai verbi precedenti, un oggetto può definire nella struttura OLEVERB verbi aggiuntivi specifici di se stesso. I numeri positivi designano questi verbi specifici dell'oggetto. Un oggetto deve considerare qualsiasi numero di verbo positivo sconosciuto come se fosse il verbo primario e restituire OLEOBJ_S_INVALIDVERB alla funzione chiamante. L'oggetto deve ignorare i verbi con numeri negativi che non riconosce e restituisce E_NOTIMPL.

Se il verbo eseguito inserisce l'oggetto nello stato in esecuzione, è necessario registrare l'oggetto nella tabella di oggetti in esecuzione (ROT) anche se l'applicazione server non supporta il collegamento. La registrazione è importante perché l'oggetto a un certo punto può fungere da origine di un collegamento in un contenitore che supporta i collegamenti agli incorporamenti. La registrazione dell'oggetto con ROT consente al client di collegamento di ottenere direttamente un puntatore all'oggetto, anziché dover passare attraverso il contenitore dell'oggetto. Per eseguire la registrazione, chiamare IOleClientSite::GetMoniker per ottenere il moniker completo dell'oggetto, chiamare la funzione GetRunningObjectTable per ottenere un puntatore a ROT e quindi chiamare IRunningObjectTable::Register.

Nota Quando l'oggetto lascia lo stato in esecuzione, ricordarsi di revocare la registrazione dell'oggetto con il rot chiamando IOleObject::Close. Se il documento contenitore dell'oggetto viene rinominato durante l'esecuzione dell'oggetto, è necessario revocare la registrazione dell'oggetto e registrarlo nuovamente con il ROT, usando il nuovo nome. Il contenitore deve informare l'oggetto del nuovo moniker chiamando IOleObject::SetMoniker o rispondendo alla chiamata di IOleClientSite::GetMoniker dell'oggetto.

Quando si mostra una finestra come risultato di IOleObject::D oVerb, è molto importante che l'oggetto chiami in modo esplicito SetForegroundWindow nella finestra di modifica. Ciò garantisce che la finestra dell'oggetto sia visibile all'utente anche se un altro processo è stato originariamente nascosto. Per altre informazioni, vedere SetForegroundWindow e SetActiveWindow.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	oleidl.h