API call from within CustomEventHandler

Hi Philippe,

I far as I know, any Perl modules in the Cpanel namespace should be available to you, at least in general. I wouldn't be surprised if there were a few out there that don't load as expected (due to compile time issues).

The thing to do is try on a non-production box. CustomEventHandlers have the capability to stop a cPanel API call, and if you make an error (syntax or otherwise), then it's very likely all the 'pre' events will be evaluated as 'false' and thus will not let the API call continue...all cPanel UI and API calls will cease to function...

Another gotcha of using the Cpanel modules directly is that there are several functions/subroutines that use 'print' statements, which under normal runtime conditions is fine, but if called out of context will likely render to the output buffer, aka STDOUT, aka whatever STDOUT is for the invocation method. This will cause UI styling to break, parsed API calls (used by the frontend) to not render data, and remote calls to be mal-formed (JSON or XML). In particular, I'm thinking about API1 calls. Granted, in somes cases (like Email.pm) the module is compiled and you won't be able to actually look at the module's subroutines to determine if they return data (with "return") or if they simply print the data (in hopes that it renders to the correct buffer). In fact the direct use of 'listpopswithdisk' as you have it in your example would be considered an API1 invocation of that function-set provided by our APIs (despite the fact that listpopwithdisk is not a real API1 function, it's only API2, but the invocation pattern holds true). However, that particular subroutine does the decent thing and returns data (ie, no 'print' statements). So, it safe in that regard.

...But anyway, I think in your case, the first step is to include the Email module.

Code:

# Get the free space for this account
use Cpanel::Email ();
my $list = Cpanel::Email::listpopswithdisk($domain, 0, 1);

Technically, you probably want to place the include closer to the top, with the rest of the includes.

Last gotcha, you will find using compiled modules particularly difficult since you cannot verify the input, and the ordering, that is required. Our documentation (cPanel & WHM's SDK) covers all the detail necessary to use the APIs. However, just because there's an API module named 'Alphabet' and function name 'xyz' that takes '1,2,3' doesn't always mean there's a literal Perl module/function like 'Cpanel::Alphabet::xyz(1,2,3)'. For instance, if you call Cpanel::Email::listpopswithdisk(), as it so happens the input ordering is a little different than the documentation. Our API parser handles this when you make an actual API request. But if you call this directly, you'll want the following order: "domain", "nearquoteonly", "regex", "no_validate".

Ideally, you'd use something like PublicAPI to make a real API call. PublicAPI lets you make an API request (as a separate, independent call); you'd actually call and API function (as documented) and not a literal module/function. I.e., no stabbing in the dark. The downside to this approach is the overhead of making the API call. But honestly, I'd do some benchmarks just to satisfy yourself that the overhead is negligible compared to the development and maintenance nightmare it can be to code against a compile, undocumented codebase (ie, Email.pm and friends).

The Perl PublicAPI package is available at our GitHub account, on CPAN, and as of 11.30 it ships in the product.

If you have an questions about PublicAPI, I'd be glad to answer them (most likely in a separate thread).

Best Regards,
-DavidN