Session.pbj

/*  CBR
 *  Session.pbj
 *
 *  Copyright (c) 2009, Ewen Cheslack-Postava
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are
 *  met:
 *  * Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *  * Neither the name of Sirikata nor the names of its contributors may
 *    be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

"pbj-0.0.3"

import "TimedMotionVector.pbj";
import "TimedMotionQuaternion.pbj";

package Sirikata.Protocol.Session;

/// Object Oriented Session Messages

message VersionInfo {
    // Unique identifier for the service, e.g. space, cppoh, katajs, etc.
    optional string name = 1;
    // String form of full version
    optional string version = 2;
    optional int32 major = 3;
    optional int32 minor = 4;
    optional int32 revision = 5;
    // Version control version -- git hash, svn revision, etc
    optional string vcs_version = 6;
}

// Connection request sent to space server, for new or migration connections
message Connect {
    enum ConnectionType {
        Fresh = 1;
        Migration = 2;
    }

    // Version of the client
    optional VersionInfo version = 11;

    required ConnectionType type = 1;

    // Requested object identifier in this space
    required uuid object = 2;
    // Optional authentication data, encoded in a byte array to
    // support a variety of authentication methods.
    optional bytes auth = 8;

    optional Sirikata.Protocol.TimedMotionVector loc = 3;
    optional Sirikata.Protocol.TimedMotionQuaternion orientation = 4;
    optional boundingsphere3f bounds = 5;
    optional float query_angle = 6; // deprecated
    optional int32 query_max_count = 10; // deprecated
    optional bytes query_parameters = 12;
    optional string mesh = 7;
    optional bytes physics = 9;
    optional bytes oh_name = 13;
    // zernike is superceded by query_data
    //    optional string zernike = 14; // deprecated
    // Additional query/implementation-specific query processor data,
    // e.g. zernike descriptor, bloom filter data, etc.
    optional bytes query_data = 15;
}

// Response to a connection request
message ConnectResponse {
    enum Response {
        Success = 1;
        Redirect = 2;
        Error = 3;
    }

    // Version of the server
    optional VersionInfo version = 8;

    required Response response = 1;
    optional uint64 redirect = 2;

    optional Sirikata.Protocol.TimedMotionVector loc = 3;
    optional Sirikata.Protocol.TimedMotionQuaternion orientation = 4;
    optional boundingsphere3f bounds = 5;
    optional string mesh = 6;
    optional bytes physics = 7;
}

// Acknowledges that a successful connection response was receive.
// Once the OH has sent this to the space, the space will start
// delivering data.
message ConnectAck {
}

// Message sent from space server to object host telling
// it that it needs to migrate
message InitiateMigration {
    required uint64 new_server = 1;
}

// Notification of disconnect - explicit ending of session
// May be sent in either direction to notify that the
// session is closed. Explicit notification is an
// optimization -- both sides will eventually close sessions
// due to timeouts
message Disconnect {
    required uuid object = 1;
    optional string reason = 2;
}

// Message about OH Coordination, can be sent in either way 
// between object host and OH coordinator
message Coordinate {
  	enum CoordinationType {
    	Add = 1;          // entity/object added
    	Remove = 2;       // entity/object removed
    	MigrateTo = 3;    // Coordinator tell an OH to migrate an entity to another OH
    	MigrateFrom = 4;  // Coordinator tell an OH to migrate an entity from another OH
    	MigrateReq = 5;   // OH send coordinator a migration request
    	Ready = 6;        // Server ready for migration
    	Ack = 7;		  // Ack message when setup connection, include migrate capacity/threshold info.
  	}
	required CoordinationType type = 1;
	optional uuid object = 2;
	optional uuid entity = 3;
	optional string oh_name = 4;
	optional int32 migrate_capacity = 5;
	optional int32 migrate_threshold = 6;
}

// Message about OH migration, can be sent in either way 
// between object host and server
message OHMigration {
  enum MigrationType {
	Object = 1;
	Entity = 2;
	Ack = 3;
  }
  required MigrationType type = 1;
  required uuid id = 2;
  optional string oh_name = 3;
  optional string password = 4;
  optional string reason = 5;
  repeated uuid objects = 6;
}

// Container for session messages.
message Container {
    // Sequence number. This isn't used for ordering, it just allows
    // unique identication of requests so that replies can be tagged
    // as being specific to a given request.
    optional uint64 seqno = 8;

    optional Connect connect = 1;
    optional ConnectResponse connect_response = 2;
    optional ConnectAck connect_ack = 3;
    optional InitiateMigration init_migration = 4;
    optional Disconnect disconnect = 5;  
    optional Coordinate coordinate = 6;
    optional OHMigration oh_migration = 7;
}