SomApply

This function invokes an apply stub. Apply stubs are never invoked directly by SOM users. The somApply function must be used instead.

Syntax

somApply(objPtr, retVal, mdPtr, args)

Parameters

objPtr (SOMObject)

A pointer to the object on which the method procedure is to be invoked.

retVal (somToken *)

A pointer to the memory region into which the result returned by the method procedure is to be copied. This pointer cannot be null (even in the case of method procedures whose returned result is void).

mdPtr (somMethodDataPtr)

A pointer to the somMethodData structure that describes the method whose procedure is to be executed by the apply stub.

args (va_list)

A va_list that contains the arguments for the method procedure. The first entry of the va_list must be objPtr. Furthermore, all arguments on the va_list must appear in widened form, as defined by ANSI C. For example, a float must appear as a double, and a char and a short must appear as the int data type. The SOM API for va_list construction ensures this.

Return Code

rc (boolean)

Remarks

This function provides a single uniform interface through which it is possible to call any method procedure. The interface is based on the caller passing: the object to which the method procedure is to be applied; a return address for the method result; a somMethodDataPtr indicating the desired method procedure; and an ANSI standard va_list structure containing the method procedure arguments. Different method procedures expect different argument types and return different result types, so the purpose of this function is to select an apply stub appropriate for the specific method involved, according to the supplied method data, and then call this apply stub. The apply stub removes the arguments from the va_list, calls the method procedure with these arguments, accepts the returned result, and then copies this result to the location pointed to by retVal.

The method procedure used by the apply stub is determined by the content of the somMethodData structure pointed to by mdPtr. The class methods somGetMethodData and somGetNthMethodData are used to load a somMethodData structure. These methods resolve static method procedures based on the receiving class's instance method table.

The SOM API requires that information necessary for selecting an apply stub be provided when a new method is registered with its introducing class (via the methods somAddStaticMethod or somAddDynamicMethod). This is required because SOM itself needs apply stubs when dispatch method resolution is used. C and C++ implementation bindings for SOM classes support this requirement, but SOM does not terminate execution if this requirement is not met by a class implementor. Thus, it is possible that there may be methods for which this function cannot select an appropriate apply stub. If an apply stub can be selected, then somApply performs as described above, and a TRUE value is returned; otherwise FALSE is returned.

Example Code

#include <somcls.xh>
#include <string.h>
#include <stdarg.h>
main()
{
    somVaBuf vb;
    va_list args;
    string result;
    SOMClass *scObj;
    somMethodData md;

    somEnvironmentNew();    /* Init environment */
    scObj = _SOMClass;   /* The SOMClass object */

    scObj->somGetMethodData(somIdFromString("somGetName"), &md);
    vb = (somVaBuf)somVaBuf_create(NULL, 0);
    somVaBuf_add(vb, (char *)&scObj, tk_ulong);
    somVaBuf_get_valist(vb, &args);

    somApply(scObj, (somToken*)&result, &md, args);
    SOM_Assert(!strcmp(result, "SOMClass"), SOM_Fatal);
    /* result is "SOMClass" */
}

Definition

SOMObject           objPtr;
somToken           *retVal;
somMethodDataPtr    mdPtr;
va_list             args;
boolean             rc;

rc = somApply(objPtr, retVal, mdPtr, args);

Related

Data Structures

• SOMObject (somobj.idl)
• somMethodData (somapi.h)
• somToken (sombtype.h)
• somMethodPtr (sombtype.h)
• va_list (stdarg.h)

Methods

• somGetMethodData
• somGetNthMethodData
• somAddDynamicMethod (somcls.idl)