Description

An object representing a portal for ArcGIS.

AGSPortal is an object that represents a view for a user (anonymous or not) into a portal. www.ArcGIS.com is an example of a portal. A portal may support subscriptions which provides organizations a sandboxed area on the portal.

AGSPortal is the main class and the entry point into the API to work with portals and organization subscriptions. It implements all the operations to interface with the backend ArcGIS Portal REST API.

Concepts:

Portals allow users and organizations to publish and share content over the web

A portal has users (AGSPortalUser), groups (AGSPortalGroup) and content (AGSPortalItem)

A portal may have users who are unaffiliated with an organization or users who are part of an organization

Users sign in to the portal and create and share content which is organized into Items. The system supports different types of items including web maps, map services (that can be used as layers in web maps), applications (that are built around web maps) and data files (that can be uploaded and downloaded).

Users can choose to keep content private or to share it with other users via groups or make content public and accessible to everyone

Users can create and join groups. Users can share items with groups. This makes the items visible to and accessible by the other members of the group.

A portal may contain multiple organizations

A user of the portal (and of the REST API) sees the view off the portal that applies to their organization subscription. This view includes users, groups and items that belong to the organization and have been shared with them. This view may also include users, groups and items that are external to the organization and have been shared with the user.

An organization has users in different roles including administrators, publishers and information workers

Administrators can add users to their organization subscriptions and have access to all content within the organization

All users can create web maps based on mashing up services that they have access to and can register services running on external servers

Publishers within an organization can in addition create hosted services based on data files that they upload

Since: 100

Inheritance diagram for AGSPortal:

Instance Methods
(void)	- cancelLoad

(void)	- doCancelLoading

(void)	- doStartLoading:

(id< AGSCancelable >)	- fetchBasemapsWithCompletion:

(id< AGSCancelable >)	- fetchDeveloperBasemapsWithCompletion:

(id< AGSCancelable >)	- fetchFeaturedGroupsWithCompletion:

(id< AGSCancelable >)	- fetchFeaturedItemsWithCompletion:

(id< AGSCancelable >)	- fetchHomePageFeaturedContentWithCompletion:

(id< AGSCancelable >)	- fetchLicenseInfoWithCompletion:

(id< AGSCancelable >)	- fetchStylesWithCompletion:

(id< AGSCancelable >)	- fetchSymbolSetsWithCompletion:

(id< AGSCancelable >)	- fetchVectorBasemapsWithCompletion:

(id< AGSCancelable >)	- findGroupsWithQueryParameters:completion:

(id< AGSCancelable >)	- findItemsWithQueryParameters:completion:

(instancetype)	- initWithURL:loginRequired:

(void)	- loadDidFinishWithError:

(void)	- loadWithCompletion:

(void)	- logout

(void)	- onLoadStatusChanged

(void)	- retryLoadWithCompletion:

Class Methods
(instancetype)	+ ArcGISOnlineWithLoginRequired:

(id< AGSCancelable >)	+ loginTypeForURL:completion:

(instancetype)	+ portalWithURL:loginRequired:

Properties
AGSCredential *	credential

NSArray< AGSPortalGroup * > *	featuredGroups

NSError *	loadError

AGSLoadStatus	loadStatus

NSLocale *	locale

BOOL	loginRequired

AGSPortalInfo *	portalInfo

AGSRequestConfiguration *	requestConfiguration

NSURL *	URL

AGSPortalUser *	user

Method Documentation

◆ ArcGISOnlineWithLoginRequired:

+ (instancetype) ArcGISOnlineWithLoginRequired: (BOOL) loginRequired

Creates a portal pointing to https://www.arcgis.com. You should load the portal by calling loadWithCompletion: (AGSLoadable-p) before using it. This is not a singleton and retuns a new portal whenever it's called.

ArcGIS Online, permits anonymous access. If you want to connect to the portal anonymously, you should set loginRequired to NO. But if you want to connect to the portal using an identity, you should set loginRequired to YES. This will ensure that API propogates the credential to the portal. If a credential is not available, an authentication challenge will be issued to first request a credential.

Parameters

loginRequired Whether or not you intend to access the portal anonymously or if you want to use a credential. If set to YES, authentication challenge will be issued. If set to NO, the portal will be accessed anonymously. If the portal does not permit anonymous access, an authentication challenge will be issued. After you instantiate the portal, if you set a credential then the credential you set will be used regardless of the loginRequired parameter.

Returns: A new portal.

Since: 100

◆ cancelLoad

- (void) cancelLoad

requiredinherited

Cancels loading if it is in progress, otherwise it does nothing. This should be called carefully because other objects could be waiting for loadWithCompletion: or retryLoadWithCompletion: to complete and this will call them all back with the error of NSUserCancelledError

Since: 100

◆ doCancelLoading

- (void) doCancelLoading

Never call this method directly. The framework calls this method on a background thread when cancelLoad (AGSLoadable-p) is called. It is meant to be overriden by subclasses. Subclasses should override this method to cancel loading their data and call loadDidFinishWithError: (AGSLoadableBase(ForSubclassEyesOnly)) at the end passing in an error representing NSUserCancelledError.

Since: 100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ doStartLoading:

- (void) doStartLoading: (BOOL) retrying

Never call this method directly. The framework calls this method on a background thread when loadWithCompletion: (AGSLoadable-p) or retryLoadWithCompletion: (AGSLoadable-p) is called. It is meant to be overriden by subclasses. Subclasses should override this method to load their data and call loadDidFinishWithError: (AGSLoadableBase(ForSubclassEyesOnly)) upon completion, passing in the error if any.

Parameters

retrying flag that is true if this method was called from retryLoadWithCompletion: (AGSLoadable-p).

Since: 100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ fetchBasemapsWithCompletion:

- (id<AGSCancelable>) fetchBasemapsWithCompletion: (nullable void(^)(NSArray< AGSBasemap * > *__nullable basemaps, NSError *__nullable error)) completion

Kicks off an operation to fetch basemaps (AGSBasemap objects) that are available for the portal. The completion block is invoked when the operation completes successfully or if an error is encountered. If the AGSPortalInfo::basemapGalleryGroupQuery property is empty, the completion block will return a nil array and no error.

Parameters

completion A block that is invoked when operation finishes.

Returns: An operation which can be canceled.

Since: 100

◆ fetchDeveloperBasemapsWithCompletion:

- (id<AGSCancelable>) fetchDeveloperBasemapsWithCompletion: (void(^)(NSArray< AGSBasemap * > *_Nullable result, NSError *_Nullable error)) completion

Executes a portal query to fetch the developer basemaps for this portal.

An AGSPortal instance may contain a set of associated basemaps, called developer basemaps, which are accessible and metered via API keys. These are equivalent to basemaps constructed via an AGSBasemapStyle.

Parameters

completion A block that is invoked when the operation finishes. The result parameter is populated if the operation completed successfully, otherwise the error parameter is populated.

Returns: An operation which can be canceled.

See also: AGSPortalInfo::developerBasemapGalleryGroupQuery, - initWithStyle: (AGSBasemap)

Since: 100.12

◆ fetchFeaturedGroupsWithCompletion:

- (id<AGSCancelable>) fetchFeaturedGroupsWithCompletion: (nullable void(^)(NSArray< AGSPortalGroup * > *__nullable featuredGroups, NSError *__nullable error)) completion

Kicks off an operation to fetch the featured groups (AGSPortalGroup objects) that are available for the portal. The completion block is invoked when the operation completes successfully or if an error is encountered. If the AGSPortalInfo::featuredGroupsQueries property is empty, the completion block will return a nil array and no error.

Parameters

completion A block that is invoked when operation finishes.

Returns: An operation which can be canceled.

Since: 100

◆ fetchFeaturedItemsWithCompletion:

- (id<AGSCancelable>) fetchFeaturedItemsWithCompletion: (nullable void(^)(NSArray< AGSPortalItem * > *__nullable featuredItems, NSError *__nullable error)) completion

Kicks off an operation to fetch the featured items (AGSPortalItem objects) that are available for the portal. The completion block is invoked when the operation completes successfully or if an error is encountered. If the AGSPortalInfo::featuredItemsGroupQuery property is empty, the completion block will return a nil array and no error.

Parameters

completion A block that is invoked when operation finishes.

Returns: An operation which can be canceled.

Since: 100

◆ fetchHomePageFeaturedContentWithCompletion:

- (id<AGSCancelable>) fetchHomePageFeaturedContentWithCompletion: (nullable void(^)(NSArray< AGSPortalItem * > *__nullable featuredItems, NSError *__nullable error)) completion

Kicks off an operation to fetch the homepage featured content (AGSPortalItem objects) that are available for the portal. The completion block is invoked when the operation completes successfully or if an error is encountered. If the AGSPortalInfo::homePageFeaturedContentGroupQuery property is empty, the completion block will return a nil array and no error.

Parameters

completion A block that is invoked when operation finishes.

Returns: An operation which can be canceled.

Since: 100

◆ fetchLicenseInfoWithCompletion:

- (id<AGSCancelable>) fetchLicenseInfoWithCompletion: (void(^)(AGSLicenseInfo *__nullable licenseInfo, NSError *__nullable error)) completion

Kicks off an operation to fetch AGSLicenseInfo entitlements and extensions for the named-user currently logged into the portal. The completion block is invoked when the operation completes successfully or if an error is encountered. Only applicable if the portal connection wasn't established anonymously.

Parameters

completion A block that is invoked when operation finishes.

Returns: An operation which can be canceled.

See also: AGSPortal::user for details about the user logged into the portal.; + setLicenseInfo:error: (AGSArcGISRuntimeEnvironment) to license the application for deployment using a named-user.

Since: 100.7

◆ fetchStylesWithCompletion:

- (id<AGSCancelable>) fetchStylesWithCompletion: (void(^)(NSArray< AGSPortalItem * > *_Nullable items, NSError *_Nullable error)) completion

Executes a portal query with the AGSPortalInfo::stylesGroupQuery query string.

Parameters

completion A block that is invoked when the operation finishes. The items parameter is populated if the operation completed successfully, otherwise the error parameter is populated.

Returns: An operation which can be canceled.

Since: 100.12

◆ fetchSymbolSetsWithCompletion:

- (id<AGSCancelable>) fetchSymbolSetsWithCompletion: (void(^)(NSArray< AGSPortalItem * > *_Nullable items, NSError *_Nullable error)) completion

Executes a portal query with the AGSPortalInfo::symbolSetsGroupQuery query string.

Parameters

completion A block that is invoked when the operation finishes. The items parameter is populated if the operation completed successfully, otherwise the error parameter is populated.

Returns: An operation which can be canceled.

Since: 100.12

◆ fetchVectorBasemapsWithCompletion:

- (id<AGSCancelable>) fetchVectorBasemapsWithCompletion: (void(^)(NSArray< AGSBasemap * > *__nullable vectorBasemaps, NSError *__nullable error)) completion

Kicks off an operation to fetch vector basemaps (AGSBasemap objects) that are available for the portal. The completion block is invoked when the operation completes successfully or if an error is encountered. If the AGSPortalInfo::vectorBasemapGalleryGroupQuery property is empty, the completion block will return a nil array and no error.

Parameters

completion A block that is invoked when operation finishes.

Returns: An operation which can be canceled.

Since: 100.6

◆ findGroupsWithQueryParameters:completion:

- (id<AGSCancelable>) findGroupsWithQueryParameters:	(AGSPortalQueryParameters *)	queryParameters
completion:	(void(^)(AGSPortalQueryResultSet __nullable resultSet, NSError __nullable error))	completion

Kicks off an operation to find groups based on the specified query. The completion block is invoked when the operation completes successfully or if an error is encountered. The resultant AGSPortalGroup objects are fully populated and have a load status of AGSLoadStatusLoaded.

Parameters

queryParameters	The query parameters to find portal groups.
completion	A block that is invoked when operation finishes.

Returns: An operation which can be canceled.

Since: 100

◆ findItemsWithQueryParameters:completion:

- (id<AGSCancelable>) findItemsWithQueryParameters:	(AGSPortalQueryParameters *)	queryParameters
completion:	(void(^)(AGSPortalQueryResultSet __nullable resultSet, NSError __nullable error))	completion

Kicks off an operation to find items based on the specified query. The completion block is invoked when the operation completes successfully or if an error is encountered. The items provided by this method are not suitable to update, delete or move because some properties, required for these operations, are not populated. Use the fetchContentWithCompletion: (AGSPortalUser) or fetchContentInFolder:completion: (AGSPortalUser) methods to get items that are fully populated. If you are considering using this method to find items that belong to a group, see findItemsWithSearchParameters:completion: (AGSPortalGroup) for a description of how that method, which uses a Group Content Search operation that's designed specifically for finding items that belong to a group, differs from this method which uses a general-purpose search operation.

Parameters

queryParameters	The query parameters to find portal items.
completion	block that is invoked when operation finishes.

Returns: An operation which can be canceled.

Since: 100

◆ initWithURL:loginRequired:

- (instancetype) initWithURL:	(NSURL *)	url
loginRequired:	(BOOL)	loginRequired

Creates a portal with a URL. You should load the portal by calling loadWithCompletion: (AGSLoadable-p) before using it.

Some portals, for instance ArcGIS Online, permit anonymous access. If you want to connect to the portal anonymously, you should set loginRequired to NO. But if you want to connect to the portal using an identity, you should set loginRequired to YES. This will ensure that API propogates the credential to the portal. If a credential is not available, an authentication challenge will be issued to first request a credential.

If the portal does not permit anonymous access, the value of loginRequired parameter is ignored. The API will attempt to propogate the credential to the portal. If a credential is not available, an authentication challenge will be issued to first request a credential.

Parameters

url The url for the portal. Eg, https://www.arcgis.com, https://www.arcgis.com/sharing/rest.

loginRequired Whether or not you intend to access the portal anonymously or if you want to use a credential. If set to YES, authentication challenge will be issued. If set to NO, the portal will be accessed anonymously. If the portal does not permit anonymous access, an authentication challenge will be issued. After you instantiate the portal, if you set a credential then the credential you set will be used regardless of the loginRequired parameter.

Since: 100

◆ loadDidFinishWithError:

- (void) loadDidFinishWithError: (nullable NSError *) error

Only subclasses should call this method in doStartLoading: (AGSLoadableBase(ForSubclassEyesOnly)) and doCancelLoading (AGSLoadableBase(ForSubclassEyesOnly)) when done loading or failed to load.

Since: 100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ loadWithCompletion:

- (void) loadWithCompletion: (nullable void(^)(NSError *__nullable error)) completion

requiredinherited

Loads data for the object asynchronously. The completion block is invoked upon completion.

You can call this method any number of times, however only one attempt is made to load the data. If it is already loading, it will just continue to load (i.e. not force a reload). If it has already loaded successfully, the completion block will be invoked right away. If it has already failed to load, the completion block will be invoked right away with error previously encountered. This method supports multiple callers and will call them all back on completion. However, each caller's completion block will be invoked once and only once.

Parameters

completion block that is invoked when object loads successfully or fails to load. An error is passed to the block if the object fails to load.

Note: The completion block is always invoked on the main thread.

Since: 100

See also: - cancelLoad to cancel loading; - retryLoadWithCompletion: to force reload

◆ loginTypeForURL:completion:

+ (id<AGSCancelable>) loginTypeForURL:	(NSURL *)	url
completion:	(void(^)(AGSPortalLoginType loginType, NSError *__nullable error))	completion

Checks login type for the given portal url. It'll return error if url require authentication or is invalid. If url requires authentication then the loginType will be either AGSPortalLoginTypeUsernamePassword or AGSPortalLoginTypeClientCertificate. If the url is invalid then loginType will be AGSPortalLoginTypeUnknown.

Parameters

url	The url for the portal. Eg, www.arcgis.com.
completion	A block that is invoked when operation finishes.

Returns: An object you can use to cancel the operation.

Since: 100

◆ logout

- (void) logout

If there is a credential for this portal then it will be set to nil and remove it from credential cache. If credential is of type OAuth then token will be invalidated.

Since: 100.2

Deprecated:: 100.6. Use AGSCredentialCache::removeAndRevokeCredential:completion or AGSCredentialCache::removeAndRevokeAllCredentialsWithCompletion instead.

◆ onLoadStatusChanged

- (void) onLoadStatusChanged

Never call this method directly. The framework calls this method on a background thread when AGSLoadable::loadStatus changes is called. Subclasses can optionally implement this to know when their loading status has changed.

Since: 100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ portalWithURL:loginRequired:

+ (instancetype) portalWithURL:	(NSURL *)	URL
loginRequired:	(BOOL)	loginRequired

Creates a portal with a URL.

You should load the portal by calling loadWithCompletion: (AGSLoadable-p) before using it.

Some portals, for instance ArcGIS Online, permit anonymous access. If you want to connect to the portal anonymously, you should set loginRequired to NO. But if you want to connect to the portal using an identity, you should set loginRequired to YES. This will ensure that API propogates the credential to the portal. If a credential is not available, an authentication challenge will be issued to first request a credential.

If the portal does not permit anonymous access, the value of loginRequired parameter is ignored. The API will attempt to propogate the credential to the portal. If a credential is not available, an authentication challenge will be issued to first request a credential.

Parameters

URL The url for the portal. Eg, https://www.arcgis.com, https://www.arcgis.com/sharing/rest.

loginRequired Whether or not you intend to access the portal anonymously or if you want to use a credential. If set to YES, authentication challenge will be issued. If set to NO, the portal will be accessed anonymously. If the portal does not permit anonymous access, an authentication challenge will be issued. After you instantiate the portal, if you set a credential then the credential you set will be used regardless of the loginRequired parameter.

Returns: A new portal.

Since: 100

◆ retryLoadWithCompletion:

- (void) retryLoadWithCompletion: (nullable void(^)(NSError *__nullable error)) completion

requiredinherited

Tries to reload when an object has failed to load. This method should be called judiciously. It should be called when:

you didn't have network connectivity earlier when it failed and you want to retry now that you have connectivity
the server was down earlier when it failed and you want to retry
the request is taking too long and you want to cancel it and retry, in which case you will first call cancelLoad and then this method

If the data hasn't started loading, it will start loading. If it is already loading, it will just continue to load. If it has already loaded successfully, calls back right away. If it has already failed to load, tries again. This method supports multiple callers and will call them all back on completion. However, each caller's completion block will be invoked once and only once.

Parameters

completion block that is invoked when object loads successfully or fails to load. An error is passed to the block if the object fails to load.

Note: The completion block is always invoked on the main thread.

Since: 100

Property Documentation

◆ credential

- (AGSCredential*) credential

readwritenonatomicstronginherited

Security credentials to access the remote resource. Only applicable if the resource is secured.

Since: 100

◆ featuredGroups

- (NSArray<AGSPortalGroup*>*) featuredGroups

readnonatomiccopy

The featured groups for the portal/organization. This property will be nil until the groups are successfully fetched with fetchFeaturedGroupsWithCompletion:. Subsequently it contains AGSPortalGroup objects that are fully populated and have a load status of AGSLoadStatusLoaded.

Since: 100

◆ loadError

- (NSError*) loadError

readnonatomicstronginherited

The error that was encountered during the most recent load operation. Will be nil if the operation succeeded.

Since: 100

◆ loadStatus

- (AGSLoadStatus) loadStatus

readrequirednonatomicassigninherited

Status of the load operation.

Since: 100

◆ locale

- (NSLocale*) locale

readwritenonatomicstrong

The locale that specifies the locale-specific formatting to use when accessing AGSPortal content. The locale provides localized content when viewing featured groups or items, adding or updating an item, adding a comment or rating to an item, and so on. If not explicitly set, NSLocale.currentLocale is used. If that locale is not supported by the portal or the property is set to nil, the locale specified in the portal/organization settings will be used. The format for locale is based on a language code and a country code separated by an underscore. Example: en_US.

Since: 100.9

◆ loginRequired

- (BOOL) loginRequired

readnonatomicassign

Determines whether to access the portal anonymously or use a credential.

See also: - initWithURL:loginRequired:; + portalWithURL:loginRequired:; + ArcGISOnlineWithLoginRequired:

Since: 100

◆ portalInfo

- (AGSPortalInfo*) portalInfo

readnonatomicstrong

Returned upon successful initialization of the portal. Contains details of the portal/organization as seen by the current user, anonymous or logged in. This property will be nil until the portal is loaded.

Since: 100

◆ requestConfiguration

- (AGSRequestConfiguration*) requestConfiguration

readwritenonatomicstronginherited

The AGSRequestConfiguration object which defines the behavior and policies to use when accessing the remote resource. The default will be nil. If it is nil the [AGSRequestConfiguration globalConfiguration] will be used.

Since: 100

◆ URL

- (NSURL*) URL

readrequirednonatomicstronginherited

The URL of the remote resource.

Since: 100

◆ user

- (AGSPortalUser*) user

readnonatomicstrong

Represents the registered user of the portal/organization and is returned upon successful initialization of the portal with a credential.

Since: 100

Description

Instance Methods

Class Methods

Properties

Method Documentation

◆ ArcGISOnlineWithLoginRequired:

◆ cancelLoad

◆ doCancelLoading

◆ doStartLoading:

◆ fetchBasemapsWithCompletion:

◆ fetchDeveloperBasemapsWithCompletion:

◆ fetchFeaturedGroupsWithCompletion:

◆ fetchFeaturedItemsWithCompletion:

◆ fetchHomePageFeaturedContentWithCompletion:

◆ fetchLicenseInfoWithCompletion:

◆ fetchStylesWithCompletion:

◆ fetchSymbolSetsWithCompletion:

◆ fetchVectorBasemapsWithCompletion:

◆ findGroupsWithQueryParameters:completion:

◆ findItemsWithQueryParameters:completion:

◆ initWithURL:loginRequired:

◆ loadDidFinishWithError:

◆ loadWithCompletion:

◆ loginTypeForURL:completion:

◆ logout

◆ onLoadStatusChanged

◆ portalWithURL:loginRequired:

◆ retryLoadWithCompletion:

Property Documentation

◆ credential

◆ featuredGroups

◆ loadError

◆ loadStatus

◆ locale

◆ loginRequired

◆ portalInfo

◆ requestConfiguration

◆ URL

◆ user