Changes between Initial Version and Version 1 of CSharpAPIs

Timestamp:

08/27/08 06:47:29 (2 years ago)

Author:

trac

Comment:

--

CSharpAPIs

@@ +1 @@
+== The C# API's for Shared Records ==
+
+The C# library is a port of some of the basic shared records functionality for .NET developers.  Provides API's for creating encrypted and unencrypted records, and handling metadata. 
+
+=== Low Level API ===
+!SharedRecords.Storage.IDataStore: this interface represents the lowest level API for dealing with records. IDataStore defines methods for creating records, retrieving records, checking for the existence of records, and adding and retrieving meta data to or from a record. IDataStore is implemented by two classes, !SharedRecords.Storage.!RemoteDataStore and !SharedRecords.Storage.!LocalDataStore. !LocalDataStore maintains a datastore on the local hard drive of the machine running the API. Records and metadata are saved and retrieved from a directory tree rooted at a directory provided by the user of the API. !RemoteDataStore uses the HTTP REST protocol described elsewhere on this wiki to save records to, and retrieve records from a datastore running on a remote server. 
+
+=== Main Application API ===
+
+!SharedRecords.Storage.IStorageProvider is an interface which exposes almost identical functionality as IDataStore, however it adds the ability to manage multiple !DataStores. The interface provides methods to create and retrieve records, to add !MetaData to and receive !MetaData from records, and to check for the existence of records. It also contains methods to add a !DataStore to those managed by the !StorageProvider, to remove a !DataStore from the !StorageProvider, and to get a list of the currently registered !DataStores. An implementation of IStorageProvider, !MultipleStorageProvider, exists in the !SharedRecords.Storage namespace which implements these functions.
+
+The IStorageProvider object also provides an [wiki:StorageProviderEvents Event Framework] for handling asynchronous uploads of records.
+
+There is also a factory class, !SharedRecords.Storage.!DataStoreFactory, which contains methods to create and initialize local or remote !DataStores. The correct !DataStore type will be created and returned, based on whether the argument passed to the factory method is an URL or a C# !DirectoryInfo object. These will create !LocalDataStores and !RemoteDataStores, respectively.
+
+== Reference ==
+
+ * [/api/CSharp CSharp Class Documentation]
+
+
+== Reference ==
+
+ * [/downloads/client/SharedRecords.dll CSharp Shared Records dll]
+
+== Code Snippets ==
+
+The following code snippet shows how to create and save a local file
+
+{{{
+        /// <summary>
+        /// Reads a file "test.doc" encrypts and saves to the configured data stores.  Reads it 
+        /// back and saves as "test-back.doc".  Assumes "test.doc" exists in the C: drive
+        /// </summary>
+        public void TestStandalone() {
+            IStorageProvider sp = StorageProviderFactory.CreateFromConfig();
+
+            string readFile = @"C:\test.doc";
+            string writeFile = @"C:\test-back.doc";
+            FileStream myFile = new FileStream(readFile, FileMode.Open, FileAccess.Read);
+            // true means encrypt it 
+            Record r = sp.CreateRecord(myFile, true);
+            Console.WriteLine("Created record: " + r);
+            FileStream myNewFile = new FileStream(writeFile, FileMode.Create, FileAccess.Write);
+            sp.GetRecord(r, myNewFile, null);
+            FileInfo sent = new FileInfo(readFile);
+            FileInfo received = new FileInfo(writeFile);
+            // do a basic sanity check - can open the file for better results
+            if (sent.Length != received.Length) {
+                throw new Exception("something went wrong.");
+            }
+        }
+}}}
+
+The following shows the same example, but manually specifying an encryption key.
+
+{{{
+        /// <summary>
+        /// The same test as above but specifying an encryption key
+        /// </summary>
+        public void TestStandaloneWithKey()
+        {
+            IStorageProvider sp = StorageProviderFactory.CreateFromConfig();
+
+            string readFile = @"C:\test.doc";
+            string writeFile = @"C:\test-back.doc";
+            FileStream myFile = new FileStream(readFile, FileMode.Open, FileAccess.Read);
+
+            // the default shared records encryption scheme
+            SymmetricAlgorithm alg = EncryptionUtils.Default;
+
+            // set the encryption key to use
+            alg.Key = StringUtils.ByteArrayFromHexString("13199834a85e3b22");
+
+            Record r = sp.CreateRecord(myFile, true, alg, null, null);
+            Console.WriteLine("Created record: " + r);
+            
+            // make sure the key is the same
+            if (!"13199834a85e3b22".Equals(r.Key))
+            {
+                throw new Exception("something went wrong - wrong key returned.");
+            }
+
+            FileStream myNewFile = new FileStream(writeFile, FileMode.Create, FileAccess.Write);
+
+            // manually create a new record for retreival with the same key
+            Record rBack = new Record();
+            rBack.Id = r.Id;
+            rBack.Key = "13199834a85e3b22";
+            
+            sp.GetRecord(rBack, myNewFile, null);
+            FileInfo sent = new FileInfo(readFile);
+            FileInfo received = new FileInfo(writeFile);
+            // do a basic sanity check - can open the file for better results
+            if (sent.Length != received.Length)
+            {
+                throw new Exception("something went wrong - bad file size");
+            }
+        }
+}}}
+
+
+
+
+
+This snippet shows how to add !MetaData to a Record, andretrieve the !MetaData associated with an Record.
+
+{{{
+        /// <summary>
+        /// This test creates a new record in each IDataStore. The test then 
+        /// creates a new MetaDataEntry associated with that record, and adds
+        /// the MetaDataEntry to the IDataStore. The test then reads back the 
+        /// MetaDataEntries held in the IDataStore.
+        /// 
+        /// This test also shows how the MetaDataEntry.ToXmlText() method 
+        /// produces well-formed Xml for any MetaDataEntry.
+        /// </summary>
+        public void GetAndAddMetaDataEntryTest()
+        {
+                // Create a new Record
+                Record record = CreateRecord(dataStore);
+
+                // Create a new MetaDataEntry
+                MetaDataEntry mde = new MetaDataEntry();
+                mde.RecordUID = record.Id;
+                mde.UserID = "User1";
+                mde.ContentType = "text/plain";
+                mde.Title = "Test Metadata";
+                mde.AddTag("Test1");
+                mde.AddTag("Test2");
+                mde.AddTag("Test3");
+                mde.UserTimeStamp = DateTime.Now;
+                MemoryStream dataStream = new MemoryStream(17);
+                StreamWriter writer = new StreamWriter(dataStream);
+                writer.Write("This is the data.");
+                writer.Flush();
+                writer.Close();
+                mde.Data = dataStream.GetBuffer();
+
+                // Add the MetaDataEntry
+                dataStore.AddMetaDataEntry(record, mde);
+                mdeList = dataStore.GetMetaData(record);
+
+                Console.WriteLine("Metadata read back from datastore {0} after add:", dataStore.ToString());
+                foreach (MetaDataEntry entry in mdeListAfter)
+                    System.Console.WriteLine(entry.ToXmlText());
+            }
+        }
+}}}
+
+Alternatively, a !MetaDataEntry can be added to the Record directly, without using
+the IDataStore:
+
+{{{
+        /// <summary>
+        /// This test creates a new record in each IDataStore. The test then 
+        /// creates a new MetaDataEntry associated with that record, and adds
+        /// the MetaDataEntry to the IDataStore.
+        /// </summary>
+        public void RecordAddMetaDataEntryTest()
+        {
+                // Create a new Record
+                Record record = CreateRecord(dataStore);
+
+                // Create a new MetaDataEntry
+                MetaDataEntry mde = new MetaDataEntry();
+                mde.RecordUID = record.Id;
+                mde.UserID = "User1";
+                mde.ContentType = "text/plain";
+                mde.Title = "Test Metadata";
+                mde.AddTag("Test1");
+                mde.AddTag("Test2");
+                mde.AddTag("Test3");
+                mde.UserTimeStamp = DateTime.Now;
+                MemoryStream dataStream = new MemoryStream(17);
+                StreamWriter writer = new StreamWriter(dataStream);
+                writer.Write("This is the data.");
+                writer.Flush();
+                writer.Close();
+                mde.Data = dataStream.GetBuffer();
+
+                // Add MetaDataEntry to Record
+                record.AddMetaDataEntry(mde);
+
+                List<MetaDataEntry> mdeList = record.GetMetaData();
+                Console.WriteLine("Metadata read back from datastore {0} after add:", dataStore.ToString());
+                foreach (MetaDataEntry entry in mdeListAfter)
+                    System.Console.WriteLine(entry.ToXmlText());
+        }
+
+}}}