acedInvoke

C++

int acedInvoke(
    const struct resbuf * args, 
    struct resbuf ** result
);

File

acedads.h

Description

Invokes an external function defined in another ARX application.

When acedInvoke() returns RTNORM, this implies that the external function was called and returned successfully. It does not imply that the external function successfully obtained a result. To determine the result, your program must inspect the result argument. If the external function failed or returned no value, result will be NULL; otherwise, result points to a list of return values.

The external function being invoked must be an external function in an ARX application currently loaded. From the external function's point of view, the acedInvoke() call is invisible. It retrieves its arguments by calling acedGetArgs() and returns a value by calling one of the value-return functions (acedRetInt(), acedRetReal(), and so on), as it does when invoked by an AutoLISP function or by the AutoCAD user.

Warning If the external function being invoked has been registered (in its application) by a call to acedRegFunc(), another function in the same application can call it--directly or indirectly--with acedInvoke(). Otherwise, acedInvoke() returns RTERROR. This also applies to a calling sequence that the first function initiates. If the calling chain leads back into the same application, acedInvoke() returns RTERROR unless the function in the same application has been registered by acedRegFunc(). To avoid acedInvoke() failure, be certain that all external functions that are meant to be called by acedInvoke() are registered by a call to acedRegFunc() after their application has successfully called acedDefun().

The first result buffer in the args list must contain the name of the external function. If the function was defined as an AutoCAD command, the string must include the C: prefix. The remaining result buffers in the args list must match the external function's argument list in their order, types, and value ranges.

If the external function has called acedRetList(), result points to a list of values.

Note An ARX application is responsible for releasing the memory that it allocates. After the external function has been invoked and its arguments processed, the application should call acutRelRb() to release the args list and the result list if *result was not NULL.

If acedInvoke() succeeds, it returns RTNORM; otherwise, it returns RTERROR. An RTERROR result indicates that the external function is not currently loaded, that it (or a function that it calls) is defined in the same application but hasn't been registered using acedRegFunc(), or that the args list contains invalid items.

Parameters

Returns

Address of an output result-buffer pointer which on success contains the external function's return values and on failure is NULL