ostinato/common/fileformat.proto

/*
Copyright (C) 2010 Srivats P.

This file is part of "Ostinato"

This is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>
*/

import "protocol.proto";

package OstProto;

enum FileType {
    kReservedFileType = 0;
    kStreamsFileType  = 1;
    kSessionFileType  = 10;
}

message FileMetaData {
    required FileType file_type = 1;
    required uint32 format_version_major = 2;
    required uint32 format_version_minor = 3;
    required uint32 format_version_revision = 4;
    required string generator_name = 5;
    required string generator_version = 6;
    required string generator_revision = 7;
}

message PortContent {
    optional Port port_config = 1;
    repeated Stream streams = 2;
    repeated DeviceGroup device_groups = 3;
}

message PortGroupContent {
    optional string server_name = 1;
    optional uint32 server_port = 2;

    repeated PortContent ports = 15;
}

message SessionContent {
    repeated PortGroupContent port_groups = 1;
}

message FileContentMatter {
    optional StreamConfigList streams = 1;
    // TODO: optional DeviceGroupConfigList device_groups = 2;
    // TODO: optional PortContent port = 3;
    // FIXME: (single) portgroup? is there a usecase for this?

    optional SessionContent session = 10;
}

/*
   An Ostinato file is the binary encoding of the File message below
   STRICTLY in increasing order of field number for the top level fields

   We do not use field number '1' for magic value because its encoded key 
   is '0a' (LF or \n) which occurs commonly in text files. Checksum should
   be the last field, so top level field numbers greater than 15 are not
   permitted. We use 15 as the checksum field number because it is the
   largest field number that can fit in a 1-byte tag

   The magic value is of a fixed length so that meta data has a fixed offset 
   from the start in the encoded message.

   Checksum is fixed length so that it is at a fixed negative offset from
   the end in the encoded message.
   
   Because the protobuf serialization API does not _guarantee_
   strict ordering, so we define wrapper messages for each top level field
   and serialize the individual wrapper messages.  The field numbers MUST 
   be the same in 'File' and the wrapper messages 
*/
message File {
    // FieldNumber 1 is reserved and MUST not be used!
    required bytes magic_value = 2;
    required FileMetaData meta_data = 3;
    optional FileContent content_matter = 9;
    required fixed32 checksum_value = 15;
}

/*
   The magic value is 10 bytes - "\xa7\xb7OSTINATO"
       The 1st-2nd byte has the MSB set to avoid mixup with text files
       The 3rd-10th byte spell OSTINATO (duh!)

   Encoded Size : Key(1) + Length(1) + Value(10) = 12 bytes
   Encoded Value: 120aa7b7 4f535449 4e41544f
*/
message FileMagic {
    required bytes value = 2;
}

message FileMeta {
    required FileMetaData data = 3;
}

message FileContent {
    optional FileContentMatter matter = 9;
}

/*
   Encoded Size : Key(1) + Value(4) = 5 bytes
   Encoded Value: 7d xxXXxxXX 
*/
message FileChecksum {
    required fixed32 value = 15; // should always be a fixed 32-bit size
}