Question

I am needing to modify an open source project to prevent reusing code (more efficient just to create a GetGameRulesPtr() function than to keep going into the engine to retrieve it. The problem is, it is stored as void **g_pGameRules. Ive never really grasped the concept of a pointer to a pointer, and I am a bit confused.

I am creating a GetGameRules() function to retrieve this pointer, but im not sure if my getter function should be void* ret type and then return *g_pGameRules, or how exactly I should go about this. I am actually brushing on my pointer usage now, but wanted to find out the proper method to learn from.

Here is the code, lines 58-89 are the SDK function that retrieve the g_pGameRules pointer from the game engine. The other functions are what I am adding the getter function to.

// extension.cpp

class SDKTools_API : public ISDKTools
{
public:
    virtual const char *GetInterfaceName()
    {
        return SMINTERFACE_SDKTOOLS_NAME;
    }

    virtual unsigned int GetInterfaceVersion()
    {
        return SMINTERFACE_SDKTOOLS_VERSION;
    }

    virtual IServer *GetIServer()
    {
        return iserver;
    }

    virtual void *GetGameRules()
    {
        return *g_pGameRules;
    }
} g_SDKTools_API;

// extension.h

namespace SourceMod
{
    /**
     * @brief SDKTools API.
     */
    class ISDKTools : public SMInterface
    {
    public:
        virtual const char *GetInterfaceName() = 0;
        virtual unsigned int GetInterfaceVersion() = 0;
    public:
        /**
         * @brief Returns a pointer to IServer if one was found.
         *
         * @return          IServer pointer, or NULL if SDKTools was unable to find one.
         */
        virtual IServer* GetIServer() = 0;

        /**
         * @brief Returns a pointer to GameRules if one was found.
         *
         * @return          GameRules pointer, or NULL if SDKTools was unable to find one.
         */
        virtual void* GetGameRules() = 0;
    };
}

// vglobals.cpp

void **g_pGameRules = NULL;
void *g_EntList = NULL;


void InitializeValveGlobals()
{
    g_EntList = gamehelpers->GetGlobalEntityList();

    char *addr;

#ifdef PLATFORM_WINDOWS
    /* g_pGameRules */
    if (!g_pGameConf->GetMemSig("CreateGameRulesObject", (void **)&addr) || !addr)
    {
        return;
    }

    int offset;
    if (!g_pGameConf->GetOffset("g_pGameRules", &offset) || !offset)
    {
        return;
    }
    g_pGameRules = *reinterpret_cast<void ***>(addr + offset);
#elif defined PLATFORM_LINUX || defined PLATFORM_APPLE
    /* g_pGameRules */
    if (!g_pGameConf->GetMemSig("g_pGameRules", (void **)&addr) || !addr)
    {
        return;
    }
    g_pGameRules = reinterpret_cast<void **>(addr);
#endif
}

Answer 1

You want to return a void*, and do the casting back to the appropriate SomeType** within implementation code. This is because void** has strange semantics (which I can’t find on google right now). It also tells more info to the user than they really need. The whole point of using void* to begin with was to avoid giving information to the user that they don’t need.

If it is an option, I’d personally recommend avoiding void* altogether, and simply providing an opaque reference type for them to call your APIs with. One way to do this would be to define a fake structure, like struct GameObjectRef {};, and pass the user back a GameObjectRef*, casted from whatever pointer your system actually uses. This allows the user to write strongly typed code, so they can’t accidentally provide the wrong pointer type to your functions, as they can with void*.

How pointers (and pointers-to-pointers) work:

Imagine you are asking me where your aunt lives. Then, I hand you a piece of paper with an address to go to. That piece of paper is a pointer to a house.

Now, take that piece of paper with the address, take a photo of it with your digital camera, and place the image onto your personal wiki site.

Now, if your sister calls, asking for your aunt’s address, just tell her to look it up on your wiki. If she asks for the URL, write it on a piece of paper for her. This second piece of paper is a pointer to a pointer to a house.

You can see how an address isn’t the same as the real thing. Just because someone has your website address doesn’t mean they know your aunt’s address. And just because they have your aunt’s address doesn’t mean they’re knocking on her door. The same is true for pointers to objects.

You can also see how you can make copies of addresses (pointers), but that doesn’t make a copy of the underlying object. When you take a photo of your aunt’s address, your aunt doesn’t get a shiny new house.

And you can see how dereferencing a pointer will lead you back to the original object. If you to go the wiki site, you get your aunt’s address. If you drive to that address, you can leave a package on her doorstep.

Note that these aren’t perfect metaphors, but they are close enough to be somewhat descriptive. Real pointers-to-pointers are a lot cleaner than those examples. They describe only two things – the type of the final object (say, GameObject), and the number of levels of indirection (say, GameObject** – two levels).