JavaScript > JavaScript for Acrobat API Reference > JavaScript API > app > app methods > trustedFunction

trustedFunction
 
S
Marks a function as trusted. Trusted functions can explicitly increase the current privilege level for their stack frame. Typically, the stack frame (which corresponds to the body of the function) contains security-restricted methods that require a privileged context in which to run. By increasing the privilege level, these restricted methods can be executed in non-privileged contexts. See Privileged versus non-privileged context.
Within the body of the function definition, calls to the app.beginPriv and app.endPriv methods must enclose any code that normally executes in a privileged context, as the examples below show.
Note: This method is available only during batch, console and application initialization events
Parameters
 
Returns
On success, returns the same function object that was passed in. After successful execution, the function object will be trusted. On error, throws NotAllowedError.
Syntax
This method can be called in two ways.
	myTrustedFunction = app.trustedFunction( 
		function() 
		{
			<function body>
		}
	);
or
	function myOtherTrustedFunction() 
	{ 
		<function body> 
	};
	app.trustedFunction(myOtherTrustedFunction);
The following examples, along with the examples following the app.trustPropagatorFunction method, contain many comments that clarify the notion of trusted function and highlight some of the nuances of the topic.
Example 1
app.newDoc is a security-restricted method that needs a privileged context in which to run. For example, it cannot normally be executed from a mouse-up event. This example shows how this method can be executed from a mouse-up event by creating a trusted function.
Place the following script in a .js file in the User (or App) JavaScript folder.
	trustedNewDoc = app.trustedFunction( function (nWidth, nHeight)
	{
		// Additional code may appear above 
		app.beginPriv();    // Explicitly raise privilege
		app.newDoc( nWidth, nHeight );
		app.endPriv();
		// Additional code may appear below.
	})
After Acrobat is restarted, the trustedNewDoc function can be executed from anywhere. The following script for a mouse-up action of a button creates a new document that is 200 points by 200 points.
	trustedNewDoc( 200, 200 );
Because of security restrictions, app.newDoc(200,200) cannot normally be executed from a mouse-up event. The trusted function permits the creation of a new document.
Note: This example is simplified. The trusted function could be modified so that it also has the two optional arguments of the app.newDoc method.
The trustedNewDoc function can also be executed as a menu item.
	app.addMenuItem( { 
		cName: "myTrustedNewDoc", 
		cUser: "New Doc", cParent: "Tools", 
		cExec: "trustedNewDoc(200,200)", nPos: 0 
	} );
Again, trustedNewDoc could be enhanced by having the user input the dimensions for the new document, either through a series of app.response dialog boxes, or a full dialog box, created by app.execDialog.
Note: If app.newDoc is not enclosed in the app.beginPriv/app.endPriv pair, executing trustedNewDoc from a non-privileged context will fail and an exception will be thrown. You must explicitly raise the privilege level in the way shown.
Example 2
The app.activeDocs property behaves differently depending on the setting:
To overcome this limitation in non-privileged context, you can define a trusted function that raises the privilege level and calls activeDocs. This function would be defined in a .js file in the User (or App) JavaScript folder.
	trustedActiveDocs = app.trustedFunction ( 
		function()
		{
			app.beginPriv(); // Explicitly raise the privilege
			var d = app.activeDocs;
			app.endPriv();
			return d;
		}
	)
The following code can be executed from a mouse-up action of a form button.
	var d = trustedActiveDocs();
	console.println("There are d = " + d.length 
		+ " files open in the viewer.")
	for ( var i=0; i< d.length; i++) 
		console.println((i+1) + ". " + d[i].documentFileName )
The console reports the number and file name of all documents—disclosed or not—open in the viewer.
Example 3
A trusted function is capable of explicitly increasing the current privilege level only for its own stack frame. This example shows some related issues.
The following code attempts to make a trusted function more modular:
	function mySaveAs(doc, path)
	{
		doc.saveAs(doc, path);
	}
	myFunc = app.trustedFunction( function (doc, path)
	{
		// privileged and/or non-privileged code here
		app.beginPriv();
		mySaveAs(doc, path);
		app.endPriv();
		// privileged and/or non-privileged code here
	}
A problem occurs because when the privileged code doc.saveAs(doc, path) is executed, it is not within the stack frame (function body) of the calling trusted function myFunc but rather within the stack frame of mySaveAs, which is not a trusted function. Therefore, when myFunc is executed in a non-privileged context, it throws an exception.
A possible solution is to make mySaveAs into a trusted function so that myFunc succeeds. However, this exposes the privileged doc.saveAs function to non-privileged execution by anyone that knows this function is on your system.
You cannot simply enclose doc.saveAs(doc,path) in a beginPriv/endPriv pair. When myFunc is run from a non-privileged context, an exception will be thrown by the app.beginPriv within the body of the mySaveAs function. This is because mySaveAs is not trusted and therefore is not authorized to request an increased privilege level.
To summarize the observations above, there is a need for a kind of function that has the following characteristics:
A trust propagator function satisfies these criteria (see trustPropagatorFunction below).