[mapguide-users] Differences between PUBLISHED_API and INTERNAL_API

[Jackie Ng]

You're mostly on the money. The purpose behind these various *_API markers
is documented here and they're mainly for controlling what gets exposed to
SWIG

https://trac.osgeo.org/mapguide/browser/trunk/MgDev/Common/Foundation/FoundationDefs.h#L49

PUBLISHED_API and EXTERNAL_API members will be exposed to the managed API
surface. Everything else will remain C++ public/private and inaccessible
from managed bindings.

As to why certain methods are marked the way they are? Only Autodesk would
know and I doubt you'll be able to get an answer from them now as to why.

Regarding your current problem. Have you looked at MgHttpRequest and
MgHttpResponse classes?

Don't let the (horrible) name deceive you, for these are the same classes
that drive all of the request handling in mapagent.fcgi meaning in your
case you could provide a grpc interface with the same request parameters
and call into the same code that the regular mapagent.fcgi handler would do.

It's probably better performance too (theoretically) as there are less
managed <-> native call transitions involved and not having to new up a
whole assortment of Mg* proxy classes to do things the non-mapagent way.
Such intermediate objects (like MgMap) would be new-d on the native side
and would be cleaned up automatically and deterministically on that same
side, without GC from the managed side.

If you need .net reference code for how to use these classes, I have an
ancient sample that demonstrates usages of MgHttpRequest and MgHttpResponse
in a custom webforms .ashx handler (yes, that ancient!)

https://github.com/jumpinjackie/mapagent-dotnet-sample/blob/master/MyCustomMapAgentHandler/mapagent.ashx.cs

But despite the ancient-ness, the usage of the classes in question can
easily be transplanted to something more modern, like an asp.net core
controller, or a GET/POST delegate handler for a minimal API or in your
case, a grpc service implementation. The only difference in all of these
transplant targets is simply:

   1. Figuring out how to set up the key/value collection of request
   parameters in the MgHttpRequest
   2. Figuring out how to output the various types that a MgHttpResponse
   could return


- Jackie

You wrote:

Hi,

So I've decided to dust off my C++ skills and did a bit of a deeper dive
into the FastCgi / HttpHandler for Mapguide. I'm trying to find new, more
efficient ways to develop applications with Mapguide and making it a part
of more complex systems, such as having a gRPC interface. I'm looking into
using .NET Core with version 8 of the framework. I believe there's a lot of
cool stuff we could make Mapguide do, but I am hitting a bit of a
performance wall on some functionalities, primarily with map draws.

The biggest challenge I'm encountering is that it appears some
functionalities are hidden away behind the INTERNAL_API flag, that I
believe just hides them from SWIG, but they still get rolled up in the C++
binaries. I did a quick check on MgPlatformBase.dll and you do get
functions like MgMapBase::SetViewCenter and MgMapBase::SetViewScale. Both
of these calls are used by the mapagent.fcgi whenever you're doing a
GetDynamicMapOverlayImage.

There's a few more of those functions that gets hidden away like that and I
feel it makes hitting better performance harder when trying to use the
exposed APIs. It also makes some functionalities impossible to do, such as
just drawing an image with the current map selection.

In keeping with my GetDynamicMapOverlayImage, if you want to do the same in
C#, you need to use RenderMap method on the MgRenderingService with all the
exposed options, versus duplicating what the FastCgi is doing and calling
up RenderDynamicOverlay. We just can't do the same in C# and it does appear
to cost 30% of performance. This is napkin benchmaking notes, I'd love to
get more concrete numbers but it's difficult when comparing apples and
oranges.

So my question is, is there an historical reasoning behind hiding away
those APIs? It feels more like an Autodesk thing than an API design thing.
Although I will admit I might be missing the reason to hide away
SetViewCenter. Maybe it's to prevent devs from shooting themselves in the
foot.

Would having a "use at your own risk" version of the API with no hidden
away to C#, Java and PHP methods be something useful for the community?
With all the work Jackie put in moving to a standard version of SWIG in
4.0, maybe it's even something someone with basic knowledge of C++ like
myself could get done?

Cheers,
Ben
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/mapguide-users/attachments/20240422/b65cae06/attachment.htm>