/************************************************************************************************** * * ADOBE SYSTEMS INCORPORATED * Copyright 2020 Adobe Systems Incorporated * All Rights Reserved. * * NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the * terms of the Adobe license agreement accompanying it. If you have received this file from a * source other than Adobe, then your use, modification, or distribution of it requires the prior * written permission of Adobe. * **************************************************************************************************/ /** Vulcan - v11.2.0 */ /** * @class Vulcan * * The singleton instance, VulcanInterface, provides an interface * to the Vulcan. Allows you to launch CC applications * and discover information about them. */ function Vulcan() {} /** * Gets all available application SAPCode-Specifiers on the local machine. * * Vulcan Control New 6.x APIs, and Deprecating older Vulcan Control APIs. * Changes : New getTargetSpecifiersEx returns productSAPCodeSpecifiers * * @return The array of all available application SAPCode-Specifiers. */ Vulcan.prototype.getTargetSpecifiersEx = function () { var params = {}; return JSON.parse( window.__adobe_cep__.invokeSync( "vulcanGetTargetSpecifiersEx", JSON.stringify(params) ) ); }; /** * Launches a CC application on the local machine, if it is not already running. * * Vulcan Control New 6.x APIs, and Deprecating older Vulcan Control APIs. * Changes : New launchAppEx uses productSAPCodeSpecifiers * * @param productSAPCodeSpecifier The application specifier; for example "ILST-25.2.3", "ILST-25", "ILST-25.2.3-en_US" and "ILST. Refer to `Documentation/CEP 11.1 HTML Extension Cookbook.md#applications-integrated-with-cep` for product SAPCode. * @param focus True to launch in foreground, or false to launch in the background. * @param cmdLine Optional, command-line parameters to supply to the launch command. * @return True if the app can be launched, false otherwise. */ Vulcan.prototype.launchAppEx = function ( productSAPCodeSpecifier, focus, cmdLine ) { if (!requiredParamsValid(productSAPCodeSpecifier)) { return false; } var params = {}; params.productSAPCodeSpecifier = productSAPCodeSpecifier; params.focus = focus ? "true" : "false"; params.cmdLine = requiredParamsValid(cmdLine) ? cmdLine : ""; return JSON.parse( window.__adobe_cep__.invokeSync("vulcanLaunchAppEx", JSON.stringify(params)) ).result; }; /** * Checks whether a CC application is running on the local machine. * * Vulcan Control New 6.x APIs, and Deprecating older Vulcan Control APIs. * Changes : New isAppRunningEx uses productSAPCodeSpecifiers * * @param productSAPCodeSpecifier The application specifier; for example "ILST-25.2.3", "ILST-25", "ILST-25.2.3-en_US" and "ILST. Refer to `Documentation/CEP 11.1 HTML Extension Cookbook.md#applications-integrated-with-cep` for product SAPCode. * @return True if the app is running, false otherwise. */ Vulcan.prototype.isAppRunningEx = function (productSAPCodeSpecifier) { if (!requiredParamsValid(productSAPCodeSpecifier)) { return false; } var params = {}; params.productSAPCodeSpecifier = productSAPCodeSpecifier; return JSON.parse( window.__adobe_cep__.invokeSync( "vulcanIsAppRunningEx", JSON.stringify(params) ) ).result; }; /** * Checks whether a CC application is installed on the local machine. * * Vulcan Control New 6.x APIs, and Deprecating older Vulcan Control APIs. * Changes : New isAppInstalledEx uses productSAPCodeSpecifiers * * @param productSAPCodeSpecifier The application specifier; for example "ILST-25.2.3", "ILST-25", "ILST-25.2.3-en_US" and "ILST. Refer to `Documentation/CEP 11.1 HTML Extension Cookbook.md#applications-integrated-with-cep` for product SAPCode. * @return True if the app is installed, false otherwise. */ Vulcan.prototype.isAppInstalledEx = function (productSAPCodeSpecifier) { if (!requiredParamsValid(productSAPCodeSpecifier)) { return false; } var params = {}; params.productSAPCodeSpecifier = productSAPCodeSpecifier; return JSON.parse( window.__adobe_cep__.invokeSync( "vulcanIsAppInstalledEx", JSON.stringify(params) ) ).result; }; /**s * Retrieves the local install path of a CC application. * * Vulcan Control New 6.x APIs, and Deprecating older Vulcan Control APIs. * Changes : New getAppPathEx uses productSAPCodeSpecifiers * * @param productSAPCodeSpecifier The application specifier; for example "ILST-25.2.3", "ILST-25", "ILST-25.2.3-en_US" and "ILST. Refer to `Documentation/CEP 11.1 HTML Extension Cookbook.md#applications-integrated-with-cep` for product SAPCode. * @return The path string if the application is found, "" otherwise. */ Vulcan.prototype.getAppPathEx = function (productSAPCodeSpecifier) { if (!requiredParamsValid(productSAPCodeSpecifier)) { return ""; } var params = {}; params.productSAPCodeSpecifier = productSAPCodeSpecifier; return JSON.parse( window.__adobe_cep__.invokeSync( "vulcanGetAppPathEx", JSON.stringify(params) ) ).result; }; /** * DEPRECATED API:: use getTargetSpecifiersEx * Gets all available application specifiers on the local machine. * * @return The array of all available application specifiers. */ Vulcan.prototype.getTargetSpecifiers = function () { console.warn( "WARNING! Function 'getTargetSpecifiers' has been deprecated, please use the new 'getTargetSpecifiersEx' function instead!" ); var params = {}; return JSON.parse( window.__adobe_cep__.invokeSync( "vulcanGetTargetSpecifiers", JSON.stringify(params) ) ); }; /** * DEPRECATED API:: use launchAppEx * Launches a CC application on the local machine, if it is not already running. * * @param targetSpecifier The application specifier; for example "indesign". * * Note: In Windows 7 64-bit or Windows 8 64-bit system, some target applications (like Photoshop and Illustrator) have both 32-bit version * and 64-bit version. Therefore, we need to specify the version by this parameter with "photoshop-70.032" or "photoshop-70.064". If you * installed Photoshop 32-bit and 64-bit on one Windows 64-bit system and invoke this interface with parameter "photoshop-70.032", you may * receive wrong result. * The specifiers for Illustrator is "illustrator-17.032", "illustrator-17.064", "illustrator-17" and "illustrator". * * In other platforms there is no such issue, so we can use "photoshop" or "photoshop-70" as specifier. * @param focus True to launch in foreground, or false to launch in the background. * @param cmdLine Optional, command-line parameters to supply to the launch command. * @return True if the app can be launched, false otherwise. */ Vulcan.prototype.launchApp = function (targetSpecifier, focus, cmdLine) { console.warn( "WARNING! Function 'launchApp' has been deprecated, please use the new 'launchAppEx' function instead!" ); if (!requiredParamsValid(targetSpecifier)) { return false; } var params = {}; params.targetSpecifier = targetSpecifier; params.focus = focus ? "true" : "false"; params.cmdLine = requiredParamsValid(cmdLine) ? cmdLine : ""; return JSON.parse( window.__adobe_cep__.invokeSync("vulcanLaunchApp", JSON.stringify(params)) ).result; }; /** * DEPRECATED API:: use isAppRunningEx * Checks whether a CC application is running on the local machine. * * @param targetSpecifier The application specifier; for example "indesign". * * Note: In Windows 7 64-bit or Windows 8 64-bit system, some target applications (like Photoshop and Illustrator) have both 32-bit version * and 64-bit version. Therefore, we need to specify the version by this parameter with "photoshop-70.032" or "photoshop-70.064". If you * installed Photoshop 32-bit and 64-bit on one Windows 64-bit system and invoke this interface with parameter "photoshop-70.032", you may * receive wrong result. * The specifiers for Illustrator is "illustrator-17.032", "illustrator-17.064", "illustrator-17" and "illustrator". * * In other platforms there is no such issue, so we can use "photoshop" or "photoshop-70" as specifier. * @return True if the app is running, false otherwise. */ Vulcan.prototype.isAppRunning = function (targetSpecifier) { console.warn( "WARNING! Function 'isAppRunning' has been deprecated, please use the new 'isAppRunningEx' function instead!" ); if (!requiredParamsValid(targetSpecifier)) { return false; } var params = {}; params.targetSpecifier = targetSpecifier; return JSON.parse( window.__adobe_cep__.invokeSync( "vulcanIsAppRunning", JSON.stringify(params) ) ).result; }; /** * DEPRECATED API:: use isAppInstalledEx * Checks whether a CC application is installed on the local machine. * * @param targetSpecifier The application specifier; for example "indesign". * * Note: In Windows 7 64-bit or Windows 8 64-bit system, some target applications (like Photoshop and Illustrator) have both 32-bit version * and 64-bit version. Therefore, we need to specify the version by this parameter with "photoshop-70.032" or "photoshop-70.064". If you * installed Photoshop 32-bit and 64-bit on one Windows 64-bit system and invoke this interface with parameter "photoshop-70.032", you may * receive wrong result. * The specifiers for Illustrator is "illustrator-17.032", "illustrator-17.064", "illustrator-17" and "illustrator". * * In other platforms there is no such issue, so we can use "photoshop" or "photoshop-70" as specifier. * @return True if the app is installed, false otherwise. */ Vulcan.prototype.isAppInstalled = function (targetSpecifier) { console.warn( "WARNING! Function 'isAppInstalled' has been deprecated, please use the new 'isAppInstalledEx' function instead!" ); if (!requiredParamsValid(targetSpecifier)) { return false; } var params = {}; params.targetSpecifier = targetSpecifier; return JSON.parse( window.__adobe_cep__.invokeSync( "vulcanIsAppInstalled", JSON.stringify(params) ) ).result; }; /** * DEPRECATED API:: use getAppPathEx * Retrieves the local install path of a CC application. * * @param targetSpecifier The application specifier; for example "indesign". * * Note: In Windows 7 64-bit or Windows 8 64-bit system, some target applications (like Photoshop and Illustrator) have both 32-bit version * and 64-bit version. Therefore, we need to specify the version by this parameter with "photoshop-70.032" or "photoshop-70.064". If you * installed Photoshop 32-bit and 64-bit on one Windows 64-bit system and invoke this interface with parameter "photoshop-70.032", you may * receive wrong result. * The specifiers for Illustrator is "illustrator-17.032", "illustrator-17.064", "illustrator-17" and "illustrator". * * In other platforms there is no such issue, so we can use "photoshop" or "photoshop-70" as specifier. * @return The path string if the application is found, "" otherwise. */ Vulcan.prototype.getAppPath = function (targetSpecifier) { console.warn( "WARNING! Function 'getAppPath' has been deprecated, please use the new 'getAppPathEx' function instead!" ); if (!requiredParamsValid(targetSpecifier)) { return ""; } var params = {}; params.targetSpecifier = targetSpecifier; return JSON.parse( window.__adobe_cep__.invokeSync("vulcanGetAppPath", JSON.stringify(params)) ).result; }; /** * Registers a message listener callback function for a Vulcan message. * * @param type The message type. * @param callback The callback function that handles the message. * Takes one argument, the message object. * @param obj Optional, the object containing the callback method, if any. * Default is null. */ Vulcan.prototype.addMessageListener = function (type, callback, obj) { if ( !requiredParamsValid(type, callback) || !strStartsWith(type, VulcanMessage.TYPE_PREFIX) ) { return; } var params = {}; params.type = type; window.__adobe_cep__.invokeAsync( "vulcanAddMessageListener", JSON.stringify(params), callback, obj ); }; /** * Removes a registered message listener callback function for a Vulcan message. * * @param type The message type. * @param callback The callback function that was registered. * Takes one argument, the message object. * @param obj Optional, the object containing the callback method, if any. * Default is null. */ Vulcan.prototype.removeMessageListener = function (type, callback, obj) { if ( !requiredParamsValid(type, callback) || !strStartsWith(type, VulcanMessage.TYPE_PREFIX) ) { return; } var params = {}; params.type = type; window.__adobe_cep__.invokeAsync( "vulcanRemoveMessageListener", JSON.stringify(params), callback, obj ); }; /** * Dispatches a Vulcan message. * * @param vulcanMessage The message object. */ Vulcan.prototype.dispatchMessage = function (vulcanMessage) { if ( !requiredParamsValid(vulcanMessage) || !strStartsWith(vulcanMessage.type, VulcanMessage.TYPE_PREFIX) ) { return; } var params = {}; var message = new VulcanMessage(vulcanMessage.type); message.initialize(vulcanMessage); params.vulcanMessage = message; window.__adobe_cep__.invokeSync( "vulcanDispatchMessage", JSON.stringify(params) ); }; /** * Retrieves the message payload of a Vulcan message for the registered message listener callback function. * * @param vulcanMessage The message object. * @return A string containing the message payload. */ Vulcan.prototype.getPayload = function (vulcanMessage) { if ( !requiredParamsValid(vulcanMessage) || !strStartsWith(vulcanMessage.type, VulcanMessage.TYPE_PREFIX) ) { return null; } var message = new VulcanMessage(vulcanMessage.type); message.initialize(vulcanMessage); return message.getPayload(); }; /** * Gets all available endpoints of the running Vulcan-enabled applications. * * Since 7.0.0 * * @return The array of all available endpoints. * An example endpoint string: * * PHXS * 16.1.0 * */ Vulcan.prototype.getEndPoints = function () { var params = {}; return JSON.parse( window.__adobe_cep__.invokeSync( "vulcanGetEndPoints", JSON.stringify(params) ) ); }; /** * Gets the endpoint for itself. * * Since 7.0.0 * * @return The endpoint string for itself. */ Vulcan.prototype.getSelfEndPoint = function () { var params = {}; return window.__adobe_cep__.invokeSync( "vulcanGetSelfEndPoint", JSON.stringify(params) ); }; /** Singleton instance of Vulcan **/ var VulcanInterface = new Vulcan(); //--------------------------------- Vulcan Message ------------------------------ /** * @class VulcanMessage * Message type for sending messages between host applications. * A message of this type can be sent to the designated destination * when appId and appVersion are provided and valid. Otherwise, * the message is broadcast to all running Vulcan-enabled applications. * * To send a message between extensions running within one * application, use the CSEvent type in CSInterface.js. * * @param type The message type. * @param appId The peer appId. * @param appVersion The peer appVersion. * */ function VulcanMessage(type, appId, appVersion) { this.type = type; this.scope = VulcanMessage.SCOPE_SUITE; this.appId = requiredParamsValid(appId) ? appId : VulcanMessage.DEFAULT_APP_ID; this.appVersion = requiredParamsValid(appVersion) ? appVersion : VulcanMessage.DEFAULT_APP_VERSION; this.data = VulcanMessage.DEFAULT_DATA; } VulcanMessage.TYPE_PREFIX = "vulcan.SuiteMessage."; VulcanMessage.SCOPE_SUITE = "GLOBAL"; VulcanMessage.DEFAULT_APP_ID = "UNKNOWN"; VulcanMessage.DEFAULT_APP_VERSION = "UNKNOWN"; VulcanMessage.DEFAULT_DATA = ""; VulcanMessage.dataTemplate = "{0}"; VulcanMessage.payloadTemplate = "{0}"; /** * Initializes this message instance. * * @param message A \c message instance to use for initialization. */ VulcanMessage.prototype.initialize = function (message) { this.type = message.type; this.scope = message.scope; this.appId = message.appId; this.appVersion = message.appVersion; this.data = message.data; }; /** * Retrieves the message data. * * @return A data string in XML format. */ VulcanMessage.prototype.xmlData = function () { if (this.data === undefined) { var str = ""; str = String.format(VulcanMessage.payloadTemplate, str); this.data = String.format(VulcanMessage.dataTemplate, str); } return this.data; }; /** * Sets the message payload of this message. * * @param payload A string containing the message payload. */ VulcanMessage.prototype.setPayload = function (payload) { var str = cep.encoding.convertion.utf8_to_b64(payload); str = String.format(VulcanMessage.payloadTemplate, str); this.data = String.format(VulcanMessage.dataTemplate, str); }; /** * Retrieves the message payload of this message. * * @return A string containing the message payload. */ VulcanMessage.prototype.getPayload = function () { var str = GetValueByKey(this.data, "payload"); if (str !== null) { return cep.encoding.convertion.b64_to_utf8(str); } return null; }; /** * Converts the properties of this instance to a string. * * @return The string version of this instance. */ VulcanMessage.prototype.toString = function () { var str = "type=" + this.type; str += ", scope=" + this.scope; str += ", appId=" + this.appId; str += ", appVersion=" + this.appVersion; str += ", data=" + this.xmlData(); return str; }; //--------------------------------------- Util -------------------------------- /** * Formats a string based on a template. * * @param src The format template. * * @return The formatted string */ String.format = function (src) { if (arguments.length === 0) { return null; } var args = Array.prototype.slice.call(arguments, 1); return src.replace(/\{(\d+)\}/g, function (m, i) { return args[i]; }); }; /** * Retrieves the content of an XML element. * * @param xmlStr The XML string. * @param key The name of the tag. * * @return The content of the tag, or the empty string * if such tag is not found or the tag has no content. */ function GetValueByKey(xmlStr, key) { if (window.DOMParser) { var parser = new window.DOMParser(); try { var xmlDoc = parser.parseFromString(xmlStr, "text/xml"); var node = xmlDoc.getElementsByTagName(key)[0]; if (node && node.childNodes[0]) { return node.childNodes[0].nodeValue; } } catch (e) { //log the error } } return ""; } /** * Reports whether required parameters are valid. * * @return True if all required parameters are valid, * false if any of the required parameters are invalid. */ function requiredParamsValid() { for (var i = 0; i < arguments.length; i++) { var argument = arguments[i]; if (argument === undefined || argument === null) { return false; } } return true; } /** * Reports whether a string has a given prefix. * * @param str The target string. * @param prefix The specific prefix string. * * @return True if the string has the prefix, false if not. */ function strStartsWith(str, prefix) { if (typeof str != "string") { return false; } return str.indexOf(prefix) === 0; } // Boilerplate Added Export export { VulcanMessage }; export default Vulcan;