3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2015 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
29 * The Cxn API allows a Civi site to initiate a connection to a
30 * remote application. There are three primary actions:
32 * - register: Establish a new connection.
33 * - unregister: Destroy an existing connection.
34 * - get: Get a list of existing connections.
38 * Adjust metadata for "register" action.
43 function _civicrm_api3_cxn_register_spec(&$spec) {
44 $daoFields = CRM_Cxn_DAO_Cxn
::fields();
45 $spec['app_guid'] = $daoFields['app_guid'];
46 $spec['app_meta_url'] = array(
47 'name' => 'app_meta_url',
48 'type' => CRM_Utils_Type
::T_STRING
,
49 'title' => ts('Application Metadata URL'),
50 'description' => 'Application Metadata URL',
52 'size' => CRM_Utils_Type
::HUGE
,
57 * Register with a remote application and create a new connection.
59 * One should generally identify an application using the app_guid.
60 * However, if you need to test a new/experimental application, then
61 * disable CIVICRM_CXN_CA and specify app_meta_url.
63 * @param array $params
65 * - app_guid: The unique identifer of the target application.
66 * - app_meta_url: The URL for the application's metadata.
70 function civicrm_api3_cxn_register($params) {
71 if (!empty($params['app_meta_url'])) {
72 list ($status, $json) = CRM_Utils_HttpClient
::singleton()->get($params['app_meta_url']);
73 if (CRM_Utils_HttpClient
::STATUS_OK
!= $status) {
74 throw new API_Exception("Failed to download appMeta. (Bad HTTP response)");
76 $appMeta = json_decode($json, TRUE);
77 if (empty($appMeta)) {
78 throw new API_Exception("Failed to download appMeta. (Malformed)");
81 elseif (!empty($params['app_guid'])) {
82 $appMeta = civicrm_api3('CxnApp', 'getsingle', array(
83 'appId' => $params['app_guid'],
87 if (empty($appMeta) ||
!is_array($appMeta)) {
88 throw new API_Exception("Missing expected parameter: app_guid");
90 \Civi\Cxn\Rpc\AppMeta
::validate($appMeta);
93 /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
94 $client = \Civi
::service('cxn_reg_client');
95 list($cxnId, $result) = $client->register($appMeta);
96 CRM_Cxn_BAO_Cxn
::updateAppMeta($appMeta);
98 catch (Exception
$e) {
99 CRM_Cxn_BAO_Cxn
::updateAppMeta($appMeta);
107 * Adjust metadata for cxn unregister.
111 function _civicrm_api3_cxn_unregister_spec(&$spec) {
112 $daoFields = CRM_Cxn_DAO_Cxn
::fields();
113 $spec['cxn_guid'] = $daoFields['cxn_guid'];
114 $spec['app_guid'] = $daoFields['app_guid'];
115 $spec['force'] = array(
117 'type' => CRM_Utils_Type
::T_BOOLEAN
,
118 'title' => ts('Force'),
119 'description' => 'Destroy connection even if the remote application is non-responsive.',
125 * Unregister with a remote application; destroy an existing connection.
127 * Specify app_guid XOR cxn_guid.
129 * @param array $params
136 function civicrm_api3_cxn_unregister($params) {
137 $cxnId = _civicrm_api3_cxn_parseCxnId($params);
138 $appMeta = CRM_Cxn_BAO_Cxn
::getAppMeta($cxnId);
140 /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
141 $client = \Civi
::service('cxn_reg_client');
142 list($cxnId, $result) = $client->unregister($appMeta, CRM_Utils_Array
::value('force', $params, FALSE));
148 * @param array $params
149 * An array with cxn_guid and/or app_guid.
151 * The CxnId. (If not available, then an exception is thrown.)
153 * @throws API_Exception
155 function _civicrm_api3_cxn_parseCxnId($params) {
158 if (!empty($params['cxn_guid'])) {
159 $cxnId = $params['cxn_guid'];
161 elseif (!empty($params['app_guid'])) {
162 $cxnId = CRM_Core_DAO
::singleValueQuery('SELECT cxn_guid FROM civicrm_cxn WHERE app_guid = %1', array(
163 1 => array($params['app_guid'], 'String'),
166 throw new API_Exception("The app_guid does not correspond to an active connection.");
170 throw new API_Exception('Missing required parameter: cxn_guid');
176 * Adjust metadata for cxn get action.
180 function _civicrm_api3_cxn_get_spec(&$spec) {
181 // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
182 unset($spec['secret']);
186 * Returns an array of Cxn records.
188 * @param array $params
189 * Array of one or more valid property_name=>value pairs.
194 function civicrm_api3_cxn_get($params) {
195 // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
196 unset($params['secret']);
198 $result = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
199 if (is_array($result['values'])) {
200 foreach (array_keys($result['values']) as $i) {
201 if (!empty($result['values'][$i]['app_meta'])) {
202 $result['values'][$i]['app_meta'] = json_decode($result['values'][$i]['app_meta'], TRUE);
204 if (!empty($result['values'][$i]['perm'])) {
205 $result['values'][$i]['perm'] = json_decode($result['values'][$i]['perm'], TRUE);
207 // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
208 unset($result['values'][$i]['secret']);
216 * Adjust metadata for "getlink" action.
221 function _civicrm_api3_cxn_getlink_spec(&$spec) {
222 $daoFields = CRM_Cxn_DAO_Cxn
::fields();
223 $spec['app_guid'] = $daoFields['app_guid'];
224 $spec['cxn_guid'] = $daoFields['cxn_guid'];
225 $spec['page'] = array(
227 'type' => CRM_Utils_Type
::T_STRING
,
228 'title' => ts('Page Type'),
229 'description' => 'The type of page (eg "settings")',
231 'size' => CRM_Utils_Type
::HUGE
,
237 * @param array $params
239 * - cxn_guid OR app_guid: string.
244 function civicrm_api3_cxn_getlink($params) {
245 $cxnId = _civicrm_api3_cxn_parseCxnId($params);
246 $appMeta = CRM_Cxn_BAO_Cxn
::getAppMeta($cxnId);
248 if (empty($params['page']) ||
!is_string($params['page'])) {
249 throw new API_Exception("Invalid page");
252 /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
253 $client = \Civi
::service('cxn_reg_client');
254 return $client->call($appMeta, 'Cxn', 'getlink', array(
255 'page' => $params['page'],
261 * @param array $params
265 function civicrm_api3_cxn_getcfg($params) {
267 'CIVICRM_CXN_CA' => defined('CIVICRM_CXN_CA') ? CIVICRM_CXN_CA
: NULL,
268 'CIVICRM_CXN_VIA' => defined('CIVICRM_CXN_VIA') ? CIVICRM_CXN_VIA
: NULL,
269 'CIVICRM_CXN_APPS_URL' => defined('CIVICRM_CXN_APPS_URL') ? CIVICRM_CXN_APPS_URL
: NULL,
270 'siteCallbackUrl' => CRM_Cxn_BAO_Cxn
::getSiteCallbackUrl(),
272 return civicrm_api3_create_success($result);
274 $cxnId = _civicrm_api3_cxn_parseCxnId($params);
275 $appMeta = CRM_Cxn_BAO_Cxn
::getAppMeta($cxnId);
277 if (empty($params['page']) ||
!is_string($params['page'])) {
278 throw new API_Exception("Invalid page");
281 /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
282 $client = \Civi\Core\Container
::singleton()->get('cxn_reg_client');
283 return $client->call($appMeta, 'Cxn', 'getlink', array(
284 'page' => $params['page'],