Função OleCreate (ole2.h)

Cria um objeto inserido identificado por um CLSID. Normalmente, você o usa para implementar o item de menu que permite que o usuário final insira um novo objeto.

Sintaxe

HRESULT OleCreate(
  [in]  REFCLSID        rclsid,
  [in]  REFIID          riid,
  [in]  DWORD           renderopt,
  [in]  LPFORMATETC     pFormatEtc,
  [in]  LPOLECLIENTSITE pClientSite,
  [in]  LPSTORAGE       pStg,
  [out] LPVOID          *ppvObj
);

Parâmetros

[in] rclsid

CLSID do objeto inserido que deve ser criado.

[in] riid

Referência ao identificador da interface, geralmente IID_IOleObject (definido nos cabeçalhos OLE como o identificador de interface para IOleObject), por meio do qual o chamador se comunicará com o novo objeto.

[in] renderopt

Um valor da enumeração OLERENDER, indicando os recursos de desenho armazenados em cache localmente que o objeto recém-criado deve ter. O valor OLERENDER escolhido afeta os valores possíveis para o parâmetro pFormatEtc .

[in] pFormatEtc

Dependendo de qual dos sinalizadores OLERENDER é usado como o valor de renderopt, ponteiro para um dos valores de enumeração FORMATETC . Consulte a enumeração OLERENDER para obter restrições. Esse parâmetro, juntamente com o parâmetro renderopt , especifica o que o novo objeto pode armazenar em cache inicialmente.

[in] pClientSite

Se você quiser que OleCreate chame IOleObject::SetClientSite, ponteiro para a interface IOleClientSite no contêiner. O valor pode ser NULL; nesse caso, você deve chamar especificamente IOleObject::SetClientSite antes de tentar operações.

[in] pStg

Ponteiro para uma instância da interface IStorage no objeto de armazenamento. Esse parâmetro pode não ser NULL.

[out] ppvObj

Endereço da variável de ponteiro que recebe o ponteiro de interface solicitado em riid. Após o retorno bem-sucedido, *ppvObject contém o ponteiro de interface solicitado.

Retornar valor

Essa função retorna S_OK com êxito e dá suporte ao valor retornado padrão E_OUTOFMEMORY.

Código de retorno	Descrição
E_OUTOFMEMORY	Memória insuficiente para a operação.

Comentários

A função OleCreate cria um novo objeto inserido e normalmente é chamada para implementar o item de menu Inserir Novo Objeto. Quando OleCreate retorna, o objeto que ele criou fica em branco (não contém dados), a menos que renderopt seja OLERENDER_DRAW ou OLERENDER_FORMAT e seja carregado. Normalmente, os contêineres chamam a função OleRun ou IOleObject::D oVerb para mostrar o objeto para edição inicial.

O parâmetro rclsid especifica o CLSID do objeto solicitado. CLSIDs de objetos registrados são armazenados no registro do sistema. Quando um usuário do aplicativo seleciona Inserir Objeto, uma caixa de seleção permite que o usuário selecione o tipo de objeto desejado daqueles no registro. Quando OleCreate é usado para implementar o item de menu Inserir Objeto, o CLSID associado ao item selecionado é atribuído ao parâmetro rclsid de OleCreate.

O parâmetro riid especifica a interface que o cliente usará para se comunicar com o novo objeto. Após o retorno bem-sucedido, o parâmetro ppvObject mantém um ponteiro para a interface solicitada.

O cache do objeto criado contém informações que permitem uma apresentação de um objeto independente quando o contêiner é aberto. Informações sobre o que deve ser armazenado em cache são passadas nos valores renderopt e pFormatetc . Quando OleCreate retorna, o cache do objeto criado não é necessariamente preenchido. Em vez disso, o cache é preenchido na primeira vez que o objeto entra no estado em execução. O chamador pode adicionar um controle de cache adicional com uma chamada para IOleCache::Cache após o retorno de OleCreate e antes que o objeto seja executado. Se renderopt for OLERENDER_DRAW ou OLERENDER_FORMAT, OleCreate exigirá que o objeto dê suporte à interface IOleCache . Não há nenhum requisito desse tipo para qualquer outro valor de renderopt.

Se pClientSite não for NULL, OleCreatechamará IOleObject::SetClientSite por meio do ponteiro pClientSite . IOleClientSite é a interface primária pela qual um objeto solicita serviços de seu contêiner. Se pClientSite for NULL, você deverá fazer uma chamada específica para IOleObject::SetClientSite antes de tentar qualquer operação.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ole2.h (inclua Ole2.h)
Biblioteca	Ole32.lib
DLL	Ole32.dll

Confira também

FORMATETC

Ioleclientsite

Ioleobject

OLERENDER