ArcGIS Runtime SDK for iOS: AGSPortal Class Reference
ArcGIS Runtime SDK for iOS  100.7
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 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.
See also
Since
100
Inheritance diagram for AGSPortal:
AGSLoadableBase <AGSRemoteResource> AGSObject <AGSLoadable>

Instance Methods

(void) - cancelLoad
 
(id< AGSCancelable >) - fetchBasemapsWithCompletion:
 
(id< AGSCancelable >) - fetchFeaturedGroupsWithCompletion:
 
(id< AGSCancelable >) - fetchFeaturedItemsWithCompletion:
 
(id< AGSCancelable >) - fetchHomePageFeaturedContentWithCompletion:
 
(id< AGSCancelable >) - fetchLicenseInfoWithCompletion:
 
(id< AGSCancelable >) - fetchVectorBasemapsWithCompletion:
 
(id< AGSCancelable >) - findGroupsWithQueryParameters:completion:
 
(id< AGSCancelable >) - findItemsWithQueryParameters:completion:
 
(instancetype) - initWithURL:loginRequired:
 
(void) - loadWithCompletion:
 
(void) - logout
 
(void) - retryLoadWithCompletion:
 

Class Methods

(instancetype) + ArcGISOnlineWithLoginRequired:
 
(id< AGSCancelable >) + loginTypeForURL:completion:
 
(instancetype) + portalWithURL:loginRequired:
 

Properties

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

Method Documentation

§ ArcGISOnlineWithLoginRequired:()

+ (instancetype) ArcGISOnlineWithLoginRequired: (BOOL)  loginRequired

Instantiates a new AGSPortal pointing to 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 false. But if you want to connect to the portal using an identity, you should set loginRequired to true. 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.
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

§ 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
completionblock that is invoked when operation finishes.
Returns
operation which can be canceled
Since
100

§ 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
completionblock that is invoked when operation finishes.
Returns
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
completionblock that is invoked when operation finishes.
Returns
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
completionblock that is invoked when operation finishes.
Returns
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
completionblock that is invoked when operation finishes.
Returns
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

§ 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
completionblock that is invoked when operation finishes.
Returns
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.
completionblock that is invoked when operation finishes
Returns
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
operation which can be canceled
Since
100

§ initWithURL:loginRequired:()

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

Instantiates the AGSPortal 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 false. But if you want to connect to the portal using an identity, you should set loginRequired to true. 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, www.arcgis.com
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

§ 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 require 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
completionblock that is invoked when operation finishes
Returns
The 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.

§ portalWithURL:loginRequired:()

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

Instantiates the AGSPortal 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 false. But if you want to connect to the portal using an identity, you should set loginRequired to true. 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, www.arcgis.com
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

§ 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

§ 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