Using C# DLLs in NeoBook

[HPW]

Hello,

It took a little more than five minutes

As Dave stated, it were some more than 5 minutes.
You are right, another example of the great support of neosoft.

Regards

[Neosoft Support]

I'm glad I could help. Keep us posted on your progress.

[Tony Kroos]

Tons of thanks again and the 5 minutes for you saved me (and most likely many others) weeks of annoying researches that have nothing to do with our daily business, so don't really bring along any benefits for us after "the job is done".

Now you have just basic and simplest example, and you are just at the beginning of your annoying researches. After you dig into marshalling datatypes and structures you will face another problem - error trapping. Read more about catching errors from unmanaged code, it's not trivial task. Then (if you have serious project) you will run into memory management issues ("garbage collect"'ed pointers and so on), syncronization issues (if u have async tasks, nb interface functions must not be called async (or via interfaces) directly)... If you'll need help I will answer smart questions regarding all this stuff.

[Neosoft Support]

Yes, memory management between two incompatible programming platforms can be very complicated. If you have any suggestions for how improve the C# template, please let us know.

[ZeeBoer]

Well i was reading into marshalling before I got into the coding and was surprised how much cleaner the template looked in C#, but sadly (even if used unaltered) NeoBook does not recognize the plugin as NeoBook plugin (I followed your instructions to rename the DLL after build into NBP, but when I try to load the plugin in NeoBook (as mentioned also after removing any of my changes), NeoBook complains that "This is not a NeoBook Plug-In!".

I might have misunderstood you here... I understood the instructions to open the solution file, build the solution (I rename the namespace by the way as you used invalid characters as if marking a variable that actually needs replacement), search for the resulting files in the /bin/debug map and rename the .dll into .nbp, then copy those files over to the neobook project in order to use them there.

Just in case I installed the VS2013 version you recommended to prevent any version conflicts, but sadly with the same result. I'm very sorry I'm bothering again at such basic problems by the way If it helps, I'm using Windows 7 64bit edition (while reading about marshalling I also read that this might matter, even tho not sure about the string parameters you marshal in the example).

Thank you very much in advance for any additional support.

With kind regards,
Bernd.

[Tony Kroos]

Set your project as 32bit application (solution platform - x86, solution configuration - release). You may not see these options on toolbar (have to enable it, see google for details), or go to project preferences. You cannot build x64 or AnyCPU plugins for Neobook, your plugin must be 32bit only since Neobook doesnt support x64.

[Neosoft Support]

Tony is correct. It must be a 32-bit dll in order to be compatible with NeoBook.

[ZeeBoer]

Sounds logical in a way... but didn't think about that possibility yet *deserved facepalm*.

Thank you very much and will try again tonight

Kind regards,
Bernd.

[ZeeBoer]

Hello dear NeoBook community.

The C# template works nicely in one direction (deliver information from NeoBook to outside C# environments). Thank you very much again for this awesome achievement! Sadly I fail to understand the syntax and functionality in depth, so I have to admit that I see myself limited to plain strings and integers (that I parse and cast from those strings) - but that's cool enough for a start. I just technically think that an array (or list, as those are internally structured the same way as arrays in C#) should be possible to handle as well somehow as it means just n-times an integer or string behind each other in the memory, even tho the length needs to be known beforehand then ofc (but that could be solved with a 2nd function that first delivers the length of the result and then another fetching the memory by knowing the length of the field). Maybe someone had a clue how this would need to look like?

Sadly the bigger problem is how I can save/return result code from a C# component into NeoBook.

The function syntax in your template seems to follow this structure:
AddActionProc(int function_id, string function_call_name_in_neobook, string function_description_in_neobook, byte[] mysterious_byte_array, int mysterious_integer, int parameter_amount);

So as you can guess: I fail to understand what the "mysterious_byte_array" and the "mysterious_integer" are used for.

Furthermore the question I ask myself is, how does the structure need to look like, when I want to return values to NeoBook (maybe even int/string arrays) and how do I access return value fields in the _nbExecAction function? It only returns bool to give a feedback over fail or success of the function (i guess) - so what other option is there to realize something in Neobook like:

C# syntax: string result = resultOfMyPluginFunction(x,y);
Pseude NeoBook syntax: SetVar "[myVariable]" resultOfMyPluginFunction(x,y)
NeoBook syntax: resultOfMyPluginFunction "x" "y" "[myVariable]" (while [myVariable] is supposed to be the target container variable where the value will be made accessable from whithin NeoBook).

Thank you very much once more for the help and support,
Bernd.

[Neosoft Support]

The only types of variables that NeoBook's scripting language are strings and integers. It cannot handle more complex data types like true arrays, pointers or objects. However, it's usually not too difficult to convert those types to strings. For example an array can be converted to a delimited string with each element separated by a comma, return, etc. character. Then in NeoBook the elements can be separated and processed as needed.

The function syntax in your template seems to follow this structure:
AddActionProc(int function_id, string function_call_name_in_neobook, string function_description_in_neobook, byte[] mysterious_byte_array, int mysterious_integer, int parameter_amount);

So as you can guess: I fail to understand what the "mysterious_byte_array" and the "mysterious_integer" are used for.

The array tells NeoBook what types of parameters the action requires. The integer tells NeoBook how many parameters there are which is the same as the length of the array.

From the Plug-in SDK help file:

In order for NeoBook to work with our Plug-In, we need to register each of our actions by providing the following information:

An ID number. This number needs to be unique within our Plug-In. However, other Plug-Ins can use the same ID numbers with any causing any conflicts. NeoBook will pass this number to the nbEditAction and nbExecAction functions to identify which of your actions needs to be processed.

A unique name. Unlike the ID number, the name cannot be used by any other actions (either NeoBook’s built-in actions or actions in other Plug-Ins). For this reason, it’s recommended that you prefix each of your actions with something unique that identifies your Plug-In. For example, if you created a Plug-In called PowerPlug, you might prefix each of your action names with “pp”. This should help limit name conflicts between Plug-Ins.

A description of the action’s purpose. Simple text string of 255 characters or less briefly describing what the action is supposed to do. (Save the detail for the manual or help file. There isn’t much room where this will be displayed.)

An array describing each parameter required by the action. The following parameter types may be used:

ACTIONPARAM_ALPHA: Parameter is a string. May contain alpha characters, numbers, punctuation, etc.
ACTIONPARAM_ALPHASP: Parameter is a string that can be spell checked.
ACTIONPARAM_NUMERIC: Parameter is a number.
ACTIONPARAM_MIXED: Parameter may be either numeric or alpha. May contain mathematical expression.
ACTIONPARAM_FILENAME: Parameter is a file name.
ACTIONPARAM_DATAFILE: Parameter is a data file name - will not be compiled inside final publication exe.
ACTIONPARAM_VARIABLE: Parameter is a variable name.
ACTIONPARAM_OBJNAME: Parameter is an object name. (NeoBook 5.0+)
ACTIONPARAM_MENUID: Parameter is a mennu item id. (NeoBook 5.0+)
ACTIONPARAM_FILENOEX: Parameter is a file name. Used by plug-ins for files that are to be compiled but not extracted. Use with nbFileToStream. (NeoBook 5.0+)
ACTIONPARAM_NONE: Use if action contains no parameters.

Finally, tell NeoBook how many parameters your action will be expecting. This should be equal to the number of items in the parameter array above or zero if ACTIONPARAM_NONE is used.

This is actually much simpler that it looks. To register an action with NeoBook, we use a special procedure called nbAddAction. The procedure simply takes the information we provide and tells NeoBook to make the action available for use. For example, if NeoBook's FileRead action were part of a Plug-In, it would be registered like this:

nbAddAction( 1, 'FileRead', 'Read something from a file.',
[ACTIONPARAM_ALPHA,ACTIONPARAM_NUMERIC,ACTIONPARAM_VARIABLE], 3 );

An example of an action that doesn’t have any parameters like NeoBook’s GotoNextPage action would look like this:

nbAddAction( 2, 'GotoNextPage', 'Go to the next page.', [ACTIONPARAM_NONE], 0 );

Furthermore the question I ask myself is, how does the structure need to look like, when I want to return values to NeoBook (maybe even int/string arrays) and how do I access return value fields in the _nbExecAction function? It only returns bool to give a feedback over fail or success of the function...

One of the parameter types above is called "ACTIONPARAM_VARIABLE". This parameter is assumed to be the name of a NeoBook variable. This is where you can insert the results of your function using the nbSetVar function defined in the C# template.

In the C# template's nbExecAction function, there is a string array called cParams that contains the parameter data passed from NeoBook. So if the first parameter of the action being executed was of the type ACTIONPARAM_VARIABLE, you could pass your function's results to that variable like this:

nbSetVar( cParams[0], "some value" );

[ZeeBoer]

Dear NeoBook support,

Thank you very much for the detailed answer and you are right, there are workarounds for arrays and other structures, but I thought (due to lacking background knowledge), I ask first before wasting tons of time on parsing while it could have been a lot easier .

Big thanks again and the input really helps a lot - the decision was made due to those possibilities, to keep realizing future projects with NeoBook as we can (thanks to your awesome support) use our existing (and future) API(s) with NeoBook.

I'd like to contribute to the community, but sadly the created plugin is totally specific to our API and indeed just translates between basic data types and the C# API and the corresponding API functions... So I cannot give more than the general recommendation that the C# template works nicely and is ready to use as bridge between NeoBook and C# developments (and created dlls).

Kind regards,
Bernd.

[Neosoft Support]

I'm happy to hear that you have everything working. Glad we could help.

[Tony Kroos]

I have a question about nbPlayAction (but it's applicable to other interface functions)...
Let's pretend we have a time-consuming action we need to play from plugin.
Remember that's a net world, so existence or memory location of an object at given time is a subject to change due to net memory management.
What happens inside nb in situations like the following...
- we have a variable with action text and we start our nbPlayAction(variable)
what if our variable doesn't exist anymore (or it's contents has changed) just right after we started nbPlayAction? Is it okay to neobook? or maybe it needs variable to be alive during nbPlayAction execution time?

- we have started nbPlayAction(variable) and immediately (first call is not finished yet) we have another call to nbPlayAction? Is interface functions thread-safe? Can it be the reason to crash?
maybe there is a reason to improve interface functions so we have a return or callback info about it's current state or just return true when job is done and false if function is still busy?

There are serious memory management problems between net and native nb I'm trying to solve, but I'm beginning to think that it's just cannot be fixed on my side... or I need to know more about inner flow of interface functions.

Update:
Looks like this could happen if variable non-valid anymore.

[Neosoft Support]

- we have a variable with action text and we start our nbPlayAction(variable)
what if our variable doesn't exist anymore (or it's contents has changed) just right after we started nbPlayAction? Is it okay to neobook? or maybe it needs variable to be alive during nbPlayAction execution time?

NeoBook is very forgiving about variables. If you try to read or write to a variable that doesn't exist, NeoBook will automatically create it for you. It's not an error to reference a variable that doesn't exist in NeoBook.

- we have started nbPlayAction(variable) and immediately (first call is not finished yet) we have another call to nbPlayAction? Is interface functions thread-safe? Can it be the reason to crash?

nbPlayAction is not thread safe because nearly every NeoBook action has the potential to update the screen. It's actually unusual to make numerous calls to nbPlayAction from a plug-in. There are occasional uses for it, but typically the role of a plug-in is to provide some type of feature NeoBook doesn't support. The out of resources error you posted appears to be coming from NeoBook's debugger. It may be that whatever you're doing is creating too many nested actions.

It's possible that there is another way of doing what you're trying to do, but without knowing more details it's difficult to make any suggestions. Are you trying to feed some kind of live data to NeoBook?

[Tony Kroos]

nbPlayAction is not thread safe because nearly every NeoBook action has the potential to update the screen. It's actually unusual to make numerous calls to nbPlayAction from a plug-in.

I'm just making neobook react to some event by playing GoSub "Subroutine", nothing unusual. And event may occur whenever it (user) wants.

Are you trying to feed some kind of live data to NeoBook?

No just making researches on net-nb interoperability in details under different circumstances.

Thanks I got your point...