I started out to find out more about AEInteractWithUser. The first thing I discovered is carbon is like a bastard child no one ever talks about.
AEInteractWithUser was mentioned in Apple's Technical Note TN2106:Scripting Interface Guidelines where it said "Before attempting to interact with the user in response to a scripting command, call AEInteractWithUser. If it returns an error, do not interact – either do without the user interface, or fail. This lets scripts specify whether or not they want to allow interaction."
The "AS hole" said "It seems ... you do not need to call AEInteractWithUser () for the library or routine on the side displaying the UI, but first execute it once to completely initialize the AppKit framework.
Your book said "AEInteractWithUser() call is part of the Carbon framework, and if the result is not 0 the script will throw an error (No user interaction allowed)."
AEInteractWithUser was mentioned in unhelpful ways in developer.apple.com under sections on kAECanSwitchLayer, kAEWaitReply, AESendMode, kAEDefaultTimeout.
It was mentioned in unhelpful ways a lot in apple's mailing list.
After searching a long time I found the first useful thing on developer.apple.com in a notice from Apple that mentioned the 3ed parameter (idleProc) of AEInteractWithUser was modified in OS X v10.11. This notice finally said what the parameters and return value is: AEInteractWithUser(_: Int32, _: NMRecPtr, _: AEIdleUPP!) -> OSErr. I'm not sure what the first parameter is but in most of the example I've seen it's -1 and now I know it's a Int32. I think it might be some kind of number used to decide when to time out. Often the parameter got set to kAEDefaultTimeout and kNoTimeOut which further supports the timeout idea.
I don't know what NMRecPtr is either. Nothing came up in Xcode help or dash but looking at examples using it seems to get used a lot with Notifications. So perhaps NMRecPtr is a pointer to a notification manager record.
I know what the third parameter is but I'm not sure how it is used for AEInteractWithUser. If I understand idleProc correctly it is used to handle things while waiting for the event manager to get back to the app.
Then after a lot more searching I found a site called stpeterandpaul.ca that mentioned a lot about AEInteractWithUser but it is on a site I know nothing about. Worse yet the full URL is http://stpeterandpaul.ca/tiger/documentation/AppleScript/Conceptual/AppleEvents/responding_aepg/chapter_6_section_2.html and the tiger in the URL suggests it's old information. But interesting enough the URL also suggests the web page is stored under conceptual things related to AppleScript and responding to AppleEvents.
This is one majorly under documented thing.
Shane can you tell me if what is written in the "Interacting With the User" section of the web page is correct and if any of my guesses are correct.