S4CreateInterface

S4CreateInterface function

Create an Interface that can be used to expose the Settlers 4 API. Consider using the S4ApiCreate to get the interface that corresponds to your header files.

Syntax

HRESULT S4CreateInterface(
	CONST GUID FAR* 	lpGUID, 
	LPIS4HOOKS FAR* 	lplpS4H
);

Parameters

lpGUID

A reference to the identifier of the interface to be used to communicate with the object.

lplpS4H

Address of pointer variable that receives the interface pointer requested in lpGUID. Upon successful return, *lplpS4H contains the requested interface pointer. Upon failure, *lplpS4H contains NULL.

Return value

The function can return the following values

Return code	Description
S_OK	An instance of the specified object class was successfully created.
E_POINTER	The lplpS4H or lpGUID parameter is NULL.
E_NOINTERFACE	The lib does not implement the requested interface, or the controlling IUnknown does not expose the requested interface.

Remarks

This function returns a COM Interface. The underlying Object implements IUnknown. Therefore, the three methods in IUnknown are the first entries in the vtable for every interface.

Before terminating an application must release all references to the COM Object by calling the Release function.

If the function fails for the first time with return code E_NOINTERFACE a message box is presented to the user informing him about a missing interface and a URL for assistance. Furthermore the UUID of the interface is displayed. When choosing to open the link the following webpage is opened: https://github.com/nyfrk/S4ModApi/issues/1.

Requirements

Minimum API Level	1
Target Edition	Any
Header	S4ModApi.h
Library	S4ModApi.lib
DLL	S4ModApi.dll

See also

S4ApiCreate