OleCreateEmbeddingHelper, fonction (ole2.h)
Crée un objet d’assistance d’incorporation OLE à l’aide du code fourni par l’application agrégé avec des éléments du gestionnaire d’objets par défaut OLE. Cet objet d’assistance peut être créé et utilisé dans un contexte et un rôle spécifiques, tels que déterminés par l’appelant.
Syntaxe
HRESULT OleCreateEmbeddingHelper(
[in] REFCLSID clsid,
[in] LPUNKNOWN pUnkOuter,
[in] DWORD flags,
[in] LPCLASSFACTORY pCF,
[in] REFIID riid,
[out] LPVOID *lplpObj
);
Paramètres
[in] clsid
CLSID de la classe à aider.
[in] pUnkOuter
Si l’assistance d’incorporation doit être agrégée, pointeur vers l’interface IUnknown de contrôle de l’objet externe. S’il ne doit pas être agrégé, bien que cela soit rare, la valeur doit être NULL.
[in] flags
DWORD contenant des indicateurs qui spécifient le rôle et le contexte de création pour l’assistance d’incorporation. Pour connaître les valeurs légales, consultez la section Notes suivante.
[in] pCF
Pointeur vers l’interface IClassFactory sur l’objet de classe utilisé par la fonction pour créer l’objet secondaire. Dans certaines situations, cette valeur peut être NULL. Pour plus d'informations, consultez la section Notes qui suit.
[in] riid
Référence à l’identificateur de l’interface souhaitée par l’appelant.
[out] lplpObj
Adresse de la variable pointeur qui reçoit le pointeur d’interface demandé dans riid. Une fois le retour réussi, *ppvObj contient le pointeur d’interface demandé sur l’assistance d’incorporation nouvellement créée.
Valeur retournée
Cette fonction retourne S_OK en cas de réussite. Les autres valeurs possibles sont les suivantes.
| Code de retour | Description |
|---|---|
|
Mémoire insuffisante pour l’opération. |
|
Un ou plusieurs paramètres ne sont pas valides. |
|
Une erreur inattendue s’est produite. |
|
L’identificateur d’interface fourni n’est pas valide. |
Remarques
La fonction OleCreateEmbeddingHelper crée un objet qui prend en charge les mêmes implémentations d’interface que celles trouvées dans le gestionnaire par défaut, mais qui a des hooks supplémentaires qui lui permettent d’être utilisé plus généralement qu’en tant qu’objet gestionnaire. Les deux appels suivants produisent le même résultat :
OleCreateEmbeddingHelper(clsid, pUnkOuter, EMBDHLP_INPROC_HANDLER |
EMBDHLP_CREATENOW, NULL, iid, ppvObj)
OleCreateDefaultHandler(clsid, pUnkOuter, iid, ppvObj)
L’assistance d’incorporation est agrégable ; pUnkOuter est le contrôle IUnknown de l’agrégat dont l’assistance d’incorporation doit faire partie. Il est utilisé pour créer une nouvelle instance du gestionnaire OLE par défaut, qui peut être utilisée pour prendre en charge des objets dans différents rôles. L’appelant passe un pointeur vers son implémentation IClassFactory à OleCreateEmbeddingHelper. Cet objet et le gestionnaire par défaut sont ensuite agrégés pour créer l’objet d’assistance d’incorporation.
La fonction OleCreateEmbeddingHelper est généralement utilisée pour prendre en charge l’une des implémentations suivantes :
-
Application objet EXE qui est utilisée à la fois comme conteneur et serveur, et qui prend en charge l’insertion d’objets dans elle-même. Dans ce cas, CreateEmbeddingHelper permet à l’objet de prendre en charge les interfaces généralement prises en charge uniquement dans le gestionnaire. Pour ce faire, l’application doit d’abord inscrire son CLSID pour différents contextes, en effectuant deux appels d’inscription à la fonction CoRegisterClassObject , au lieu d’un seul, comme suit :
CoRegisterClassObject(clsidMe, pUnkCfLocal, CLSCTX_LOCAL_SERVER, REGCLS_MULTI_SEPARATE...) CoRegisterClassObject(clsidMe, pUnkCfInProc, CLSCTX_INPROC_SERVER, REGCLS_MULTI_SEPARATE...)Dans ces appels, vous transmettez différentes implémentations de fabrique de classes à chacune de pUnkCfLocal et pUnkCfInProc. La fabrique de classes pointée par pUnkCfLocal serait utilisée pour créer des objets qui doivent être incorporés dans un processus distant, ce qui est le cas normal qui utilise un objet gestionnaire associé au client. Toutefois, lorsqu’un serveur crée un objet et l’incorpore en lui-même, pUnkCfInProc pointe vers un objet de classe qui peut créer un objet qui prend en charge les interfaces de gestionnaire. La classe locale est utilisée pour créer l’objet et la classe in-process crée l’assistance d’incorporation, en passant le pointeur vers la fabrique de classe du premier objet dans pCF.
- Gestionnaire d’objets in-process personnalisé, auquel cas la DLL crée l’assistance d’incorporation en passant un pointeur vers une implémentation privée d’IClassFactory dans pCF.
| Valeurs du paramètre flags | Objectif |
|---|---|
| EMBDHLP_INPROC_HANDLER | Crée une assistance d’incorporation qui peut être utilisée avec des applications d’objet DLL ; Plus précisément, l’assistance expose les fonctionnalités de mise en cache du gestionnaire d’objets par défaut. |
| EMBDHLP_INPROC_SERVER | Crée une assistance d’incorporation qui doit être utilisée dans le cadre d’un serveur in-process. pCF ne peut pas être NULL. |
| EMBDHLP_CREATENOW | Crée immédiatement l’objet secondaire à l’aide de pCF ; si pCF a la valeur NULL, le gestionnaire de proxy standard est utilisé. |
| EMBDHLP_DELAYCREATE | Retarde la création de l’objet secondaire jusqu’à ce qu’il soit nécessaire (lorsque l’assistance est placée dans l’état d’exécution) pour améliorer la vitesse et l’utilisation de la mémoire. pCF ne doit pas être NULL. L’indicateur EMBDHLP_INPROC_HANDLER ne peut pas être utilisé avec cet indicateur. |
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | ole2.h |
| Bibliothèque | Ole32.lib |
| DLL | Ole32.dll |
| Ensemble d’API | ext-ms-win-com-ole32-l1-1-5 (introduit dans Windows 10, version 10.0.15063) |