/*
 * Copyright 2011 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
//
// Specification of  protocol buffers that are used with the Android
// service.
//
// Note: unless otherwise specified in a comment, all fields in all messages
// are required, even though they are listed as optional.

syntax = "proto2";

package com.google.protos.ipc.invalidation;

option optimize_for = LITE_RUNTIME;

option java_outer_classname = "AndroidService";


import "client_protocol.proto";
import "java_client.proto";

// Call from application to Ticl.

message ClientDowncall {
  message StartDowncall {}
  message StopDowncall {}
  message AckDowncall {
    optional bytes ack_handle = 1;
  }
  message RegistrationDowncall {
    repeated ObjectIdP registrations = 1;
    repeated ObjectIdP unregistrations = 2;
  }

  // Serial number to prevent intent reordering.
  // TODO: use.
  optional int64 serial = 1;
  optional Version version = 2;

  // Exactly one of the following fields must be set.
  optional StartDowncall start = 3;
  optional StopDowncall stop = 4;
  optional AckDowncall ack = 5;
  optional RegistrationDowncall registrations = 6;
}

// Internal (non-public) call from application to Ticl.
message InternalDowncall {
  message ServerMessage {
    optional bytes data = 1;
  }
  message NetworkStatus {
    optional bool is_online = 1;
  }
  message CreateClient {
    optional int32 client_type = 1;  //  client type code.
    optional bytes client_name = 2;  //  application client id.
    optional ClientConfigP client_config = 3;  // Client config.

    // Whether the client should not be started on creation. Must always be
    // false for production use.
    optional bool skip_start_for_test = 4;
  }
  optional Version version = 1;

  // Exactly one must be set.
  optional ServerMessage server_message = 2;
  optional NetworkStatus network_status = 3;
  optional bool network_addr_change = 4;
  optional CreateClient create_client = 5;
}

// Upcall from Ticl to application listener.

message ListenerUpcall {
  message ReadyUpcall {}

  message InvalidateUpcall {
    // Required.
    optional bytes ack_handle = 1;

    // Exactly one must be set.
    optional InvalidationP invalidation = 2;
    optional ObjectIdP invalidate_unknown = 3;
    optional bool invalidate_all = 4;
  }

  message RegistrationStatusUpcall {
    optional ObjectIdP object_id = 1;
    optional bool is_registered = 2;
  }

  message RegistrationFailureUpcall {
    optional ObjectIdP object_id = 1;
    optional bool transient = 2;
    optional string message = 3;
  }

  message ReissueRegistrationsUpcall {
    optional bytes prefix = 1;
    optional int32 length = 2;
  }

  message ErrorUpcall {
    optional int32 error_code = 1;
    optional string error_message = 2;
    optional bool is_transient = 3;
  }

  // Serial number to prevent intent reordering. Not currently used.
  // TODO: use
  optional int64 serial = 1;
  optional Version version = 2;

  // Exactly one must be sent.
  optional ReadyUpcall ready = 3;
  optional InvalidateUpcall invalidate = 4;
  optional RegistrationStatusUpcall registration_status = 5;
  optional RegistrationFailureUpcall registration_failure = 6;
  optional ReissueRegistrationsUpcall reissue_registrations = 7;
  optional ErrorUpcall error = 8;
}

// Internal proto used by the Android scheduler to represent an event to run.
message AndroidSchedulerEvent {
  optional Version version = 1;

  // Name of the recurring task to execute.
  optional string event_name = 2;

  // Generation number of the Ticl with which this event is associated. Used to
  // prevent old events from accidentally firing on new Ticls.
  optional int64 ticl_id = 3;
}

// Internal proto used by the Android network to represent a message to send
// to the data center from the client.
message AndroidNetworkSendRequest {
  optional Version version = 1;  // Required
  optional bytes message = 2;  // Required
}

// Protocol buffer used to store state for a persisted Ticl.
message AndroidTiclState {
  message Metadata {
    // All fields are required.
    optional int32 client_type = 1;  //  client type code.
    optional bytes client_name = 2;  //  application client id.
    optional int64 ticl_id = 3;      // Ticl uniquifier.
    optional ClientConfigP client_config = 4;  //  client config.
  }
  optional Version version = 1;
  optional InvalidationClientState ticl_state = 2;  // Marshalled Ticl.
  optional Metadata metadata = 3;  // Extra state needed to construct a Ticl.
}

// An AndroidTiclState state plus a digest; this is the protocol buffer actually
// stored persistently by the service.
message AndroidTiclStateWithDigest {
  optional AndroidTiclState state = 1;
  optional bytes digest = 2;  // Digest of "state."
}