EldoS | Feel safer!

Software components for data protection, secure storage and transfer

.NET API type discrepancies

Also by EldoS: Rethync
The cross-platform framework that simplifies synchronizing data between mobile and desktop applications and servers and cloud storages
#16144
Posted: 03/28/2011 14:37:43
by Mel Reyes (Standard support level)
Joined: 03/28/2011
Posts: 10

I am noticing a number of API methods in the CallbackFileSystem class that contain different types in the implementation as opposed to the documentation.

In particular, rather than Int64, several (but not all) of the methods utilize the CBFS_LARGE_INTEGER type for their "FileId" parameters.

I assume I can just populate the data in the "QuadPart" member of the CBFS_LARGE_INTEGER struct, but why do some class members expose this struct and other class members expose the parameter as an Int64?
#16145
Posted: 03/28/2011 15:10:44
by Eugene Mayevski (EldoS Corp.)

CBFS_LARGE_INTEGER is used only for FileId in exactly two callback declarations, used for enumerating the files. FileId was added in CBFS 3.0 when we added support for file identification by ID. While I can't tell you about particular reasons for this, I believe the developers had some.

Now, it would help both of us a lot if you told me what other discrepancies did you come across, so that we could update the docs (or the code if apropriate).


Sincerely yours
Eugene Mayevski
#16146
Posted: 03/28/2011 16:07:42
by Mel Reyes (Standard support level)
Joined: 03/28/2011
Posts: 10

CbFsGetFileNameByFileIdEvent uses an Int64 for this field.

In the HTML Help documentation, all three functions show the type (as Int64). So it makes me confused as to why it has to use this struct (which is typically only necessary in C/C++ and not C#) on 2 of the 3 functions and not all of them.

It causes compile time errors if you copy/paste the signatures from the HTML help into your source code.

Also in the HTML Help documentation, the OnCloseVolume event is missing altogether.

As well, several functions have C++ syntax in the C# signatures within the HTML help. I don't remember which ones and I don't have time to go back and make a list at the moment, but just wanted to let you know in case you have time to go through it later.

I noticed this because I tried to copy/paste the signatures into my source code from the HTML help to speed up the process.

I also found it frustrating that because these events are defined as "delegate" instead of "event" in the .NET API, it breaks Visual Studio Intellisense that would otherwise automatically generate method stubs when you write code subscribing to the event. I guess it was done because an event would allow multiple delegates to be assigned to it and you want to prohibit this usage pattern, but I found it a tad frustrating all the same.
#16147
Posted: 03/29/2011 04:12:51
by Eugene Mayevski (EldoS Corp.)

Thank you for information.

Quote
Vincent Ugenti wrote:
So it makes me confused as to why it has to use this struct (which is typically only necessary in C/C++ and not C#) on 2 of the 3 functions and not all of them.


We couldn't find out yesterday the exact reason for that complex type to be used, but developers confirm that there was some.

The docs are written by hand, so copy/paste mistakes are possible. We fix them as they are reported.

Quote
Vincent Ugenti wrote:
Also in the HTML Help documentation, the OnCloseVolume event is missing altogether.


It has been deprecated and the topic was removed intentionally. The code was kept because existing (old) code probably references this event. The same applies to OnOpenVolume.

Quote
Vincent Ugenti wrote:
As well, several functions have C++ syntax in the C# signatures within the HTML help.


I will review this now.

Quote
Vincent Ugenti wrote:
I guess it was done because an event would allow multiple delegates to be assigned to it and you want to prohibit this usage pattern


Either this or managed C++ didn't allow event declaration. I have to check this as well. Unfortunately we can't change the APIs now.


Sincerely yours
Eugene Mayevski
#16148
Posted: 03/29/2011 04:25:37
by Eugene Mayevski (EldoS Corp.)

I've checked the event list and most methods and the only thing I have found was that in 4 event declarations "CallbackFileSystem" type (the first parameter of the event) was present as "CallbackFileSystem ^" (due to copy/paste mistake). That has been corrected. If you find other mismatches, please let us know (just method names), we will update docs as well.

As a side note - I agree that automated help generation tools would eliminate this problem, but we have yet to find (or write) a tool that will be able to parse the number of APIs and *update* the help file the way we need. Due to our specific requirements we had to write our own help authoring tool - no tool on the market matched our needs at least partially.


Sincerely yours
Eugene Mayevski
#16151
Posted: 03/29/2011 10:52:30
by Mel Reyes (Standard support level)
Joined: 03/28/2011
Posts: 10

Hi Eugene,

Thanks for being so attentive, I appreciate the fast replies.

Just to be clear, these are not issues that are preventing me from using / evaluating the product but just kind of for your informational purposes.

Almost complete with my initial implementation of my filesystem so I am sure the "real" questions will be coming at you soon enough. :)

Thanks again,

Vincent
#19321
Posted: 03/07/2012 10:49:13
by Ivan P (Priority Standard support level)
Joined: 04/11/2011
Posts: 66

Hi Eugeny,

Quote
Eugene Mayevski wrote:
Also in the HTML Help documentation, the OnCloseVolume event is missing altogether.

It has been deprecated and the topic was removed intentionally. The code was kept because existing (old) code probably references this event. The same applies to OnOpenVolume.


Could you then add [ObsoleteAttribute] attribute with appropriate message to these methods (and any other deprecated ones) so that developers can see that they shouldn't subscribe to these events?

And regarding the FileId parameter. It's still unclear for me if it's supported or not and how it can be used.

The CbFsEnumerateDirectoryEvent description in HTML help says: "FileId - Currently unused". Should I return value of 0 or anything else in this callback (in examples 0 is passed, but no word in the doc about it)? Is OnGetFileNameByFileId callback optional?

Thanks,
IP
#19324
Posted: 03/07/2012 13:03:31
by Eugene Mayevski (EldoS Corp.)

As we are moving to version 4, we will remove those events altogether.

FileId is supported and can be used if you handle all FileId-related stuff.

File IDs can be used instead of file names and are used by NT Services for Unix module of Windows Server OS (I can be mistaken with the exact name). Some other applications might also use them when available (though practical use of those ID besides mentioned services is not known).

You need to provide a unique numeric ID for each file. If you have a global directory of files, then it's easy - you probably have an ID in that directory. Otherwise you would have to invent some.

But in fact File IDs were implemented upon request from one of our customers who needed to support the above mentioned service.


Sincerely yours
Eugene Mayevski
Also by EldoS: CallbackProcess
A component to control process creation and termination in Windows and .NET applications.

Reply

Statistics

Topic viewed 2742 times

Number of guests: 1, registered members: 0, in total hidden: 0




|

Back to top

As of July 15, 2016 EldoS Corporation will operate as a division of /n software inc. For more information, please read the announcement.

Got it!