gRPC

The gRPC external interface exposes the same functionality described for JSON-RPC. The full gRPC interface is described in a .proto file from which snippets are included here. Communication stubs for a wide variety of languages are available making it easy to get started with an integration.

In the following a few of the services exposed are detailed since the functionality and semantics of the services are identical to the JSON-RPC methods with the same names.

Services

ContextManager

The ContextManager service contains the primary endpoints for joining a context and initiating context transactions.

service ContextManager {
	// SetActive switches active status of the manager.
	rpc SetActive (SetActiveRequest) returns (SetActiveResponse);
	// JoinCommonContext throws AlreadyJoined, TooManyParticipants, TransactionInProgress, ContextNotActive
	rpc JoinCommonContext (JoinCommonContextRequest) returns (JoinCommonContextResponse);
	// LeaveCommonContext raises(UnknownParticipant)
	rpc LeaveCommonContext (LeaveCommonContextRequest) returns (LeaveCommonContextResponse);
	// StartContextChanges raises(UnknownParticipant, TransactionInProgress, InvalidTransaction)
	rpc StartContextChanges (StartContextChangesRequest) returns (StartContextChangesResponse);
	// EndContextChanges raises(InvalidContextCoupon, NotInTransaction, InvalidTransaction)
	rpc EndContextChanges (EndContextChangesRequest) returns (EndContextChangesResponse);
	// UndoContextChanges raises(InvalidContextCoupon, NotInTransaction, UndoNotPossible)
	rpc UndoContextChanges (UndoContextChangesRequest) returns (UndoContextChangesResponse);
	// PublishChangesDecision raises(NotInTransaction, InvalidContextCoupon, ChangesNotEnded, AcceptNotPossible)
	rpc PublishChangesDecision (PublishChangesDecisionRequest) returns (PublishChangesDecisionResponse);
	// SuspendParticipation raises(UnknownParticipant)
	rpc SuspendParticipation (SuspendParticipationRequest) returns (SuspendParticipationResponse);
	// ResumeParticipation raises(UnknownParticipant, TransactionInProgress)
	rpc ResumeParticipation (ResumeParticipationRequest) returns (ResumeParticipationResponse);
	// MostRecentContextCoupon return the most recent context coupons.
	rpc MostRecentContextCoupon (MostRecentContextCouponRequest) returns (MostRecentContextCouponResponse);
	// InstanceInformation is information about this ContextManager.
	rpc InstanceInformation (InstanceInformationRequest) returns (InstanceInformationResponse);
	// ImplementationInformation returns information about this component.
	rpc ImplementationInformation (ImplementationInformationRequest) returns (ImplementationInformationResponse);
	rpc ContextParticipantStream (stream ContextParticipantStreamRequest) returns (stream ContextParticipantStreamResponse);
}

JoinCommonContext

The JoinCommonContextRequest for instance is defined as:

message JoinCommonContextRequest {
	// Identifies the recipient of the message.
	string component_identifier = 1;
	string participant = 2;
	string application_name = 3;
	bool survey = 4;
	bool wait = 5;
}

and the corresponding JoinCommonContextResponse is then:

message JoinCommonContextResponse {
	int64 participant_coupon = 1;
	string instructions = 2;
	string component_i_d = 3;
}

ContextData

The ContextData service methods are primarily used once a context transaction has been initiated via ContextManager.StartContextChanges to query the changes done here.

service ContextData {
	// GetItemNames returns names of all items.
	rpc GetItemNames (GetItemNamesRequest) returns (GetItemNamesResponse);
	// DeleteItems will delete an item in the shared context.
	rpc DeleteItems (DeleteItemsRequest) returns (DeleteItemsResponse);
	// SetItemValues changes the values of the given entries (keyed by name).
  // raises(NotInTransaction, UnknownParticipant, InvalidContextCoupon,
  // NameValueCountMismatch, BadItemNameFormat, BadItemType, BadItemValue, ChangesNotPossible, ChangesNotAllowed)
	rpc SetItemValues (SetItemValuesRequest) returns (SetItemValuesResponse);
	// GetItemValues returns the stored item values for the given keys.
  // raises(InvalidContextCoupon, BadItemNameFormat, UnknownItemName)
	rpc GetItemValues (GetItemValuesRequest) returns (GetItemValuesResponse);
}

ContextAction

The ContextAction service is used to invoke pre-configured actions via the CM.

service ContextAction {
	// Perform a context action
	rpc Perform (PerformRequest) returns (PerformResponse);
}

Perform

Has the following request definition:

message PerformRequest {
	// Identifies the recipient of the message.
	string component_identifier = 1;
	int64 participant_coupon = 2;
	string action_identifier = 3;
	repeated string input_names = 4;
	repeated string input_values = 5;
	string app_signature = 6;
}

And corresponding response:

message PerformResponse {
	int64 action_coupon = 1;
	repeated string output_names = 2;
	repeated string output_values = 3;
	string manager_signature = 4;
}

Streams

In order to query and notify the ContextParticipant a bi-directional stream is used.

The messages going to the CP (the “responses”) and those coming from the CP to the CM (the “requests”) are defined as follows:

//ContextParticipantStream
// ContextManager.ContextParticpantStream Request/Response
// This handles both ContextParticipant and ContextAgent interactions
// Response are messages sent to the client. Requests are messages received from the client.
message ContextParticipantStreamResponse {
	message ContextChangesPendingResponse {
		int64 context_coupon = 1;
	}
	message ContextChangesAcceptedResponse {
		int64 context_coupon = 1;
	}
	message ContextChangesCanceledResponse {
		int64 context_coupon = 1;
	}
	message CommonContextTerminatedResponse {}
	message PingResponse {}
	message ErrorResponse {
		string error = 1;
		ContextParticipantStreamRequest original = 2;
	}
	message AgentContextChangesPendingResponse {
		int64 context_coupon = 1;
		int64 agent_coupon = 2;
		string principal = 3;
		repeated string item_names = 4;
		repeated string item_values = 5;
		string manager_signature = 6;
		string action_identifier = 7;
	}
	message ParticipantNotification {
		enum ParticipantNotificationEvent {
			PARTICIPANT_JOINED = 0;
			PARTICIPANT_LEFT = 1;
			PARTICIPANT_SUSPENDED = 2;
			PARTICIPANT_RESUMED = 3;
			PARTICIPANT_ALREADY_HERE = 4;
		}
		ParticipantNotificationEvent event = 1;
		string application_name = 2;
		int64 participant_coupon = 3;
	}
	message ApplicationNotification {
		enum ApplicationNotificationEvent {
			APPLICATION_LAUNCHED = 0;
		}
		ApplicationNotificationEvent event = 1;
		string application_name = 2;
		int64 window_handle = 3;
		int64 process_id = 4;
	}
	oneof content {
		JoinCommonContextResponse join_common_context = 1;
		ContextChangesPendingResponse context_changes_pending = 2;
		ContextChangesAcceptedResponse context_changes_accepted = 3;
		ContextChangesCanceledResponse context_changes_canceled = 4;
		CommonContextTerminatedResponse common_context_terminated = 5;
		PingResponse ping = 6;
		ErrorResponse error = 7;
		AgentContextChangesPendingResponse agent_context_changes_pending = 8;
		ParticipantNotification participant_notification = 9;
		ApplicationNotification application_notification = 10;
	}
}

message ContextParticipantStreamRequest {
	message ContextChangesPendingRequest {
		int64 context_coupon = 1;
		string decision = 2;
		string reason = 3;
	}
	message PongRequest {}
	message AgentContextChangesPendingRequest {
		int64 context_coupon = 1;
		int64 agent_coupon = 2;
		string agent_signature = 3;
		string decision = 4;
		string reason = 5;
		repeated string item_names = 6;
		repeated string item_values = 7;
	}
	oneof content {
		JoinCommonContextRequest join_common_context = 1;
		ContextChangesPendingRequest context_changes_pending = 2;
		PongRequest pong = 3;
		AgentContextChangesPendingRequest agent_context_changes_pending = 4;
	}
}

The full gRPC protocol definition is available on request.