Murl::Addons::Facebook::IControl Interface Referenceabstract

The Facebook IControl interface. More...

#include "murl_addons_facebook_i_control.h"

Inherited by Murl::Addons::Facebook::Android::Control, and Murl::Addons::Facebook::Ios::Control.

Classes

class  RequestParameters
 The request parameters class. More...
 
class  ShareParameters
 The share parameters class. More...
 

Public Types

enum  Status {
  STATUS_IDLE, STATUS_OPEN_SESSION_BUSY, STATUS_SESSION_READY, STATUS_AUTHORIZE_READ_BUSY,
  STATUS_AUTHORIZE_PUBLISH_BUSY, STATUS_OPEN_SESSION_FAILED, STATUS_CLOSE_SESSION_BUSY, STATUS_ERROR
}
 Enumeration of the facebook session status. More...
 
enum  Audience { AUDIENCE_NONE, AUDIENCE_ONLY_ME, AUDIENCE_FRIENDS, AUDIENCE_EVERYONE }
 Enumeration of the facebook audience. More...
 
enum  SendStatus {
  SEND_IDLE, SEND_REQUEST_BUSY, SEND_REQUEST_CONFIRMED, SEND_REQUEST_CANCELLED,
  SEND_SHARE_BUSY, SEND_SHARE_CONFIRMED, SEND_SHARE_CANCELLED, SEND_ERROR
}
 Enumeration of the facebook send status. More...
 
enum  RequestStatus { REQUEST_IDLE, REQUEST_GRAPH_BUSY, REQUEST_GRAPH_DONE, REQUEST_ERROR }
 Enumeration of the facebook request status. More...
 
enum  ErrorCategory {
  ERROR_CATEGORY_NONE, ERROR_CATEGORY_RETRY, ERROR_CATEGORY_AUTHENTICATION_REOPEN_SESSION, ERROR_CATEGORY_PERMISSIONS,
  ERROR_CATEGORY_SERVER, ERROR_CATEGORY_THROTTLING, ERROR_CATEGORY_OTHER, ERROR_CATEGORY_BAD_REQUEST,
  ERROR_CATEGORY_USER_CANCELLED, ERROR_CATEGORY_CLIENT
}
 Enumeration of the facebook error categories. More...
 
typedef Map< String, StringGraphResult
 Definition of the Facebook Graph result map. More...
 
typedef Array< GraphResultGraphResultArray
 Definition of an array containing Facebook Graph results. More...
 

Public Member Functions

virtual Status GetStatus () const =0
 Get the facebook session status. More...
 
virtual Bool ClearStatus ()=0
 Clear the facebook session status. More...
 
virtual Bool OpenSession (const StringArray &permissions, Bool allowUI=true)=0
 Opening a session with Facebook. More...
 
virtual Bool AuthorizeReadPermissions (const StringArray &permissions)=0
 Requests new or additional read permissions for the session. More...
 
virtual Bool AuthorizePublishPermissions (const StringArray &permissions, Audience audience)=0
 Requests new or additional write permissions for the session. More...
 
virtual Bool CloseSession ()=0
 Close the session with Facebook. More...
 
virtual SendStatus GetSendStatus () const =0
 Get the facebook send status. More...
 
virtual Bool ClearSendStatus ()=0
 Clear the send status. More...
 
virtual Bool SendRequest (const RequestParameters &requestParameters)=0
 Presents a Facebook app-request dialog. More...
 
virtual const RequestParametersGetRequestParameters () const =0
 Get the request parameters. More...
 
virtual Bool SendShare (const ShareParameters &shareParameters, Bool modally=true)=0
 Presents a Facebook share-request dialog. More...
 
virtual const ShareParametersGetShareParameters () const =0
 Get the share parameters. More...
 
virtual RequestStatus GetRequestStatus () const =0
 Get the facebook request status. More...
 
virtual Bool ClearRequestStatus ()=0
 Clear the request status. More...
 
virtual Bool RequestGraph (const String &graphPath, const StringArray &parameters, const String &httpMethod="GET")=0
 Request to Facebook Graph. More...
 
virtual const GraphResultArrayGetGraphResults () const =0
 Get the result from a Facebook Graph request. More...
 
virtual const StringGetAppLinkURL () const =0
 Get the app link URL string. More...
 
virtual Bool ClearAppLinkURL ()=0
 Clear the app link URL string. More...
 
virtual ErrorCategory GetLastErrorCategory () const =0
 Get the error category of the last error. More...
 
virtual const StringGetLastError () const =0
 Get the description string of the last error. More...
 
virtual const StringGetLastNotifyUserError () const =0
 Get a message string suitable for display to the user of the last error. More...
 
virtual Bool ClearLastError ()=0
 Clear the last error state and string. More...
 

Detailed Description

The Facebook IControl interface.

Member Typedef Documentation

◆ GraphResult

Definition of the Facebook Graph result map.

The map-key is the name of the field.

◆ GraphResultArray

Definition of an array containing Facebook Graph results.

Member Enumeration Documentation

◆ Status

Enumeration of the facebook session status.

Use GetStatus() to get the current status.

Enumerator
STATUS_IDLE 

The facebook session is idle.

STATUS_OPEN_SESSION_BUSY 

Open facebook session is in progress.

STATUS_SESSION_READY 

The facebook session is ready.

STATUS_AUTHORIZE_READ_BUSY 

Authorize read permissions is in progress.

STATUS_AUTHORIZE_PUBLISH_BUSY 

Authorize publish permissions is in progress.

STATUS_OPEN_SESSION_FAILED 

Open facebook session has failed.

STATUS_CLOSE_SESSION_BUSY 

Close facebook session is in progress.

STATUS_ERROR 

Session error.

◆ Audience

Enumeration of the facebook audience.

Enumerator
AUDIENCE_NONE 

No audience needed.

This value is useful for cases where data will only be read from Facebook.

AUDIENCE_ONLY_ME 

Indicates that only the user is able to see posts made by the application.

AUDIENCE_FRIENDS 

Indicates that the user's friends are able to see posts made by the application.

AUDIENCE_EVERYONE 

Indicates that all Facebook users are able to see posts made by the application.

◆ SendStatus

Enumeration of the facebook send status.

Use GetSendStatus() to get the current send status.

Enumerator
SEND_IDLE 

The send status is idle.

SEND_REQUEST_BUSY 

Send request is in progress.

SEND_REQUEST_CONFIRMED 

Send request has been confirmed.

SEND_REQUEST_CANCELLED 

Send request has been cancelled.

SEND_SHARE_BUSY 

Send share is in progress.

SEND_SHARE_CONFIRMED 

Send share has been confirmed.

SEND_SHARE_CANCELLED 

Send share has been cancelled.

SEND_ERROR 

Send error.

◆ RequestStatus

Enumeration of the facebook request status.

Use GetRequestStatus() to get the current request status.

Enumerator
REQUEST_IDLE 

The request status is idle.

REQUEST_GRAPH_BUSY 

The request for me is in progress.

REQUEST_GRAPH_DONE 

The request for me has been done.

REQUEST_ERROR 

Request error.

◆ ErrorCategory

Enumeration of the facebook error categories.

Use GetLastErrorCategory() to get the last error category.

Enumerator
ERROR_CATEGORY_NONE 

No error.

ERROR_CATEGORY_RETRY 

Indicates that the error may be authentication related but the application should retry the operation.

This case may involve user action that must be taken, and so the application should also check GetLastNotifyUserError() and if available display to the user before retrying.

ERROR_CATEGORY_AUTHENTICATION_REOPEN_SESSION 

Indicates that the error is authentication related and the application should reopen the session.

ERROR_CATEGORY_PERMISSIONS 

Indicates that the error is permission related.

ERROR_CATEGORY_SERVER 

Indicates that the error implies that the server had an unexpected failure or may be temporarily down.

ERROR_CATEGORY_THROTTLING 

Indicates that the error results from the server throttling the client.

ERROR_CATEGORY_OTHER 

Indicates that the error is Facebook-related but is uncategorizable, and likely newer than the current version of the SDK.

ERROR_CATEGORY_BAD_REQUEST 

Indicates that the error is an application error resulting in a bad or malformed request to the server.

ERROR_CATEGORY_USER_CANCELLED 

Indicates the user cancelled the operation.

This error is only applied on iOS platforms.

ERROR_CATEGORY_CLIENT 

Indicates that this is a client-side error.

Examples of this can include, but are not limited to, JSON parsing errors or IOExceptions. This error is only applied on Anroid platforms.

Member Function Documentation

◆ GetStatus()

virtual Status Murl::Addons::Facebook::IControl::GetStatus ( ) const
pure virtual

Get the facebook session status.

The session operation works asynchronously, the application can check the current state to operate correctly.

Returns
The facebook session status.

◆ ClearStatus()

virtual Bool Murl::Addons::Facebook::IControl::ClearStatus ( )
pure virtual

Clear the facebook session status.

If the session status is IFacebookControl::STATUS_OPEN_SESSION_FAILED or IFacebookControl::STATUS_ERROR, the session status is set to IFacebookControl::STATUS_SESSION_READY or IFacebookControl::STATUS_IDLE depending on the previsous session state.
See also GetLastError() and ClearLastError() for IFacebookControl::STATUS_ERROR.

Returns
true if successful.

◆ OpenSession()

virtual Bool Murl::Addons::Facebook::IControl::OpenSession ( const StringArray permissions,
Bool  allowUI = true 
)
pure virtual

Opening a session with Facebook.

When opening the session, the status changes to IFacebookControl::STATUS_OPEN_SESSION_BUSY immediately. When the open is finished the status changes to IFacebookControl::STATUS_SESSION_READY. If the open fails, the status changes to IFacebookControl::STATUS_OPEN_SESSION_FAILED.

Parameters
permissionsAn array of strings representing the read permissions to request during the authentication flow. It is not allowed to pass publish permissions to this method.
allowUISometimes it is useful to attempt to open a session, but only if no login UI will be required to accomplish the operation. For example, at application startup it may not be desirable to transition to login UI for the user, and yet an open session is desired so long as a cached token can be used to open the session. Passing false to this argument, assures the method will not present UI to the user in order to open the session.
Returns
true if successful.

◆ AuthorizeReadPermissions()

virtual Bool Murl::Addons::Facebook::IControl::AuthorizeReadPermissions ( const StringArray permissions)
pure virtual

Requests new or additional read permissions for the session.

When requesting permissions, the status changes to IFacebookControl::STATUS_AUTHORIZE_READ_BUSY immediately. When the request is finished the status changes to IFacebookControl::STATUS_SESSION_READY.
If the request fails, the status changes to IFacebookControl::STATUS_ERROR.

Parameters
permissionsAn array of strings representing the permissions to request during the authentication flow. An empty array indicates basic permissions.
Returns
true if successful.

◆ AuthorizePublishPermissions()

virtual Bool Murl::Addons::Facebook::IControl::AuthorizePublishPermissions ( const StringArray permissions,
Audience  audience 
)
pure virtual

Requests new or additional write permissions for the session.

When requesting permissions, the status changes to IFacebookControl::STATUS_AUTHORIZE_PUBLISH_BUSY immediately. When the request is finished the status changes to IFacebookControl::STATUS_SESSION_READY.
If the request fails, the status changes to IFacebookControl::STATUS_ERROR.

Parameters
permissionsAn array of strings representing the permissions to request during the authentication flow.
audienceSpecifies the audience for posts.
Returns
true if successful.

◆ CloseSession()

virtual Bool Murl::Addons::Facebook::IControl::CloseSession ( )
pure virtual

Close the session with Facebook.

When closing the session, the status changes to IFacebookControl::STATUS_CLOSE_SESSION_BUSY immediately. When the logout is finished the status changes to IFacebookControl::STATUS_IDLE.

Returns
true if successful.

◆ GetSendStatus()

virtual SendStatus Murl::Addons::Facebook::IControl::GetSendStatus ( ) const
pure virtual

Get the facebook send status.

The send operation works asynchronously, the application can check the current state to operate correctly.

Returns
The facebook send status.

◆ ClearSendStatus()

virtual Bool Murl::Addons::Facebook::IControl::ClearSendStatus ( )
pure virtual

Clear the send status.

If the send status is not IFacebookControl::SEND_REQUEST_BUSY and not IFacebookControl::SEND_SHARE_BUSY the send status is set to SEND_IDLE.
This is useful to clear the status after getting a CONFIRMED / CANCELLED or IFacebookControl::SEND_ERROR via GetSendStatus().
See also GetLastError() and ClearLastError() for IFacebookControl::SEND_ERROR.

Returns
true if successful.

◆ SendRequest()

virtual Bool Murl::Addons::Facebook::IControl::SendRequest ( const RequestParameters requestParameters)
pure virtual

Presents a Facebook app-request dialog.

When sending a request, the send status changes to IFacebookControl::SEND_REQUEST_BUSY immediately. When the request is finished the send status changes to IFacebookControl::SEND_REQUEST_CONFIRMED or IFacebookControl::SEND_REQUEST_CANCELLED.
Use ClearSendStatus() after processing the send status.

Parameters
requestParametersThe request parameters class.
Returns
true if successful.

◆ GetRequestParameters()

virtual const RequestParameters& Murl::Addons::Facebook::IControl::GetRequestParameters ( ) const
pure virtual

Get the request parameters.

Returns
The request parameters.

◆ SendShare()

virtual Bool Murl::Addons::Facebook::IControl::SendShare ( const ShareParameters shareParameters,
Bool  modally = true 
)
pure virtual

Presents a Facebook share-request dialog.

When sending a share, the send status changes to IFacebookControl::SEND_SHARE_BUSY immediately. When the share is finished the send status changes to IFacebookControl::SEND_SHARE_CONFIRMED or IFacebookControl::SEND_SHARE_CANCELLED.
Use ClearSendStatus() after processing the send status.

Parameters
shareParametersThe share parameters class.
modallyIf false the share dialog is presented in the facebook app if possible.
Returns
true if successful.

◆ GetShareParameters()

virtual const ShareParameters& Murl::Addons::Facebook::IControl::GetShareParameters ( ) const
pure virtual

Get the share parameters.

The share parameters may be set during app start, if the send status is IFacebookControl::SEND_SHARE_CONFIRMED or IFacebookControl::SEND_SHARE_CANCELLED.
This happens if the app was killed during switch to share dialog in the facebook app.

Returns
The share parameters.

◆ GetRequestStatus()

virtual RequestStatus Murl::Addons::Facebook::IControl::GetRequestStatus ( ) const
pure virtual

Get the facebook request status.

The request operation works asynchronously, the application can check the current state to operate correctly.

Returns
The facebook request status.

◆ ClearRequestStatus()

virtual Bool Murl::Addons::Facebook::IControl::ClearRequestStatus ( )
pure virtual

Clear the request status.

If the request status is not IFacebookControl::REQUEST_GRAPH_BUSY the send status is set to REQUEST_IDLE.
This is useful to clear the status after getting IFacebookControl::REQUEST_GRAPH_DONE or IFacebookControl::REQUEST_ERROR via GetRequestStatus().
See also GetLastError() and ClearLastError() for IFacebookControl::REQUEST_ERROR.

Returns
true if successful.

◆ RequestGraph()

virtual Bool Murl::Addons::Facebook::IControl::RequestGraph ( const String graphPath,
const StringArray parameters,
const String httpMethod = "GET" 
)
pure virtual

Request to Facebook Graph.

When sending a request, the request status changes to IFacebookControl::REQUEST_GRAPH_BUSY immediately. When the request is finished the request status changes to IFacebookControl::REQUEST_GRAPH_DONE.
Use GetGraphResults() to get the result data from the request. Use ClearRequestStatus() after processing the request status.

Parameters
graphPathThe Graph API endpoint to use for the request, for example "me".
parametersThe parameters for the request. An empty array sends only the automatically handled parameters, for example, the access token. The first element is the "key" and the second element is the corresponding value,
The third element is the "key" and the fourth element is the corresponding value,
and so on...
httpMethodThe HTTP method to use for the request. An empty string implies a GET.
Returns
true if successful.

◆ GetGraphResults()

virtual const GraphResultArray& Murl::Addons::Facebook::IControl::GetGraphResults ( ) const
pure virtual

Get the result from a Facebook Graph request.

Returns
The result from a Facebook Graph request.

◆ GetAppLinkURL()

virtual const String& Murl::Addons::Facebook::IControl::GetAppLinkURL ( ) const
pure virtual

Get the app link URL string.

Returns
The app link URL string.

◆ ClearAppLinkURL()

virtual Bool Murl::Addons::Facebook::IControl::ClearAppLinkURL ( )
pure virtual

Clear the app link URL string.

Returns
true if successful.

◆ GetLastErrorCategory()

virtual ErrorCategory Murl::Addons::Facebook::IControl::GetLastErrorCategory ( ) const
pure virtual

Get the error category of the last error.

Use ClearLastError() to reset the error category.

Returns
The error category of the last error.

◆ GetLastError()

virtual const String& Murl::Addons::Facebook::IControl::GetLastError ( ) const
pure virtual

Get the description string of the last error.

Use ClearLastError() to reset the error state.

Returns
The description string of the last error.

◆ GetLastNotifyUserError()

virtual const String& Murl::Addons::Facebook::IControl::GetLastNotifyUserError ( ) const
pure virtual

Get a message string suitable for display to the user of the last error.

The message is describing a user action necessary to enable Facebook functionality. Use ClearLastError() to reset the error state.

Returns
A message string suitable for display to the user or an empty string if no message is available for the last error.

◆ ClearLastError()

virtual Bool Murl::Addons::Facebook::IControl::ClearLastError ( )
pure virtual

Clear the last error state and string.

If the session state is IFacebookControl::STATUS_ERROR, the state is set to IFacebookControl::STATUS_SESSION_READY or IFacebookControl::STATUS_IDLE depending on the previsous session state.
If the send state is IFacebookControl::SEND_ERROR, the send state is set to IFacebookControl::SEND_IDLE.
If the request state is IFacebookControl::REQUEST_ERROR, the request state is set to IFacebookControl::REQUEST_IDLE.
Set the last error category to IFacebookControl::ERROR_CATEGORY_NONE.
Clear the last error and the notify user error string.

Returns
true if successful.

The documentation for this interface was generated from the following file:
  • murl_addons_facebook_i_control.h


Copyright © 2011-2018 Spraylight GmbH.