adds an API function to get information about upcoming events

[samhatchett]

I tried to make this as non-invasive as possible - but i did change the signature for a very old function to return an index instead of being declared void. Added doxy markup for an explanation of the new API.

[eladsal]

@samhatchett , in line 647 the control index is not returned, is it because its not needed there?

[samhatchett]

@eladsal that's right - the old behavior doesn't change within that calling code, this PR just hijacks the control timestep function get information back about which element caused the control action so it can be used by the new calling code.

[eladsal]

Thank you. Can you please also add the single-threaded version of the function?

[samhatchett]

@eladsal yes, I would be happy to add s/t versions.

[samhatchett]

@eladsal I have made the suggested changes, if you wouldn't mind taking a look. thanks!

[eladsal]

@samhatchett my concern is with the eventType in EN_timetonextevent. Such a type may be difficult to use in other programming languages. For example, in EN_getlinktype we use an Int for the link type. Is there a function we use a user-defined type?

[samhatchett]

@eladsal Looking over this again, I'm re-discovering that the C API relies on client code to handle the implicit casting from enum types to integers. I will change the new functions to reflect that convention. Thanks for the comments, and i regret that it's taken me this long to circle back!

[eladsal]

Thank you @samhatchett, I think we are good to go.