ArcGIS Runtime SDK for iOS: AGSPortal Class Reference
ArcGIS Runtime SDK for iOS  100.15
AGSPortal Class Reference

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 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:
AGSLoadableBase <AGSRemoteResource> AGSObject <AGSLoadable>

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

AGSCredentialcredential
 
NSArray< AGSPortalGroup * > * featuredGroups
 
NSError * loadError
 
AGSLoadStatus loadStatus
 
NSLocale * locale
 
BOOL loginRequired
 
AGSPortalInfoportalInfo
 
AGSRequestConfigurationrequestConfiguration
 
NSURL * URL
 
AGSPortalUseruser
 

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
loginRequiredWhether 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
retryingflag 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
completionA 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
completionA 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
completionA 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
completionA 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
completionA 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
completionA 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
completionA 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
completionA 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
completionA 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
queryParametersThe query parameters to find portal groups.
completionA 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
queryParametersThe query parameters to find portal items.
completionblock 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
urlThe url for the portal. Eg, https://www.arcgis.com, https://www.arcgis.com/sharing/rest.
loginRequiredWhether 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
completionblock 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
urlThe url for the portal. Eg, www.arcgis.com.
completionA 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
URLThe url for the portal. Eg, https://www.arcgis.com, https://www.arcgis.com/sharing/rest.
loginRequiredWhether 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:

  1. you didn't have network connectivity earlier when it failed and you want to retry now that you have connectivity
  2. the server was down earlier when it failed and you want to retry
  3. 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
completionblock 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