Hi All, I've been working on an API extension for media-service-upnp that will allow clients to easily upload files to a DMS. I have a working implementation on my fork but I thought it might be a good idea to discuss the API changes here before sending my pull request. The plan is as follows: Add four new methods to the com.intel.UPnP.MediaDevice interface. 1) Upload(s DisplayName, s FilePath, o ContainerPath) -> (i TransferID, o ObjectPath) This command would initiate the upload of the local file specified by FilePath to the Container specified by ContainerPath. The file will be assigned the Friendly Name DisplayName. This method creates a new empty object on the server and instructs the server to begin to upload the local file from the client. The Upload method returns as soon as the server has begun to upload the file and not when the server has finished uploading the file. Upload returns two output parameters: a TransferID that can be used to monitor the upload and to cancel it, and ObjectPath which contains the path of the newly created object. An example of invoking this function with mediaconsole would be upnp = UPNP() upnp.servers() MediaTomb /com/intel/MediaServiceUPnP/server/0 My Media /com/intel/MediaServiceUPnP/server/1 device = Device("/com/intel/MediaServiceUPnP/server/1") device.upload("Test", "/home/user/Pictures/Cherry Tree.jpg", "/com/intel/MediaServiceUPnP/server/1/37663139343730303264363066666130 36326631613838316232376538353139") Transfer ID: 3 Path: /com/intel/MediaServiceUPnP/server/1/653565366537366266383766393834613 5633063643761373236623663346239 2) GetTransferStatus(i TransferID) -> (s TransferStatus, i TransferLength, i TransferTotal) Retrieves information on the status of an upload operation. TransferID is the ID returned by a call to Upload. The method returns a TransferStatus which can be set to 1 of 4 values, "IN_PROGRESS", "STOPPED", "ERROR", "COMPLETED", and two integers which indicate the total length of the transfer and the amount of bytes transferred so far. GetTransferStatus will return valid results for up to 30 seconds after the transfer has finished. 3) CancelTransfer(i TransferID) Cancels an ongoing transfer. 4) GetCurrentTransfers() -> (ai) Returns an array of transfer IDs of the transfers currently in progress. This is my proposal. I'm wondering whether to provide a notification to indicate whether the transfer has completed or failed. Currently, I'm not planning to do this but I'd like to hear your thoughts. My feeling is that upload clients will need to call GetTransferStatus periodically to determine how the transfer is progressing, and so will not need this extra signal. On the other hand, if we want to implement an upload manager that monitors all the uploads being made to the server, regardless of their initiators, we would need some signals. Alternative Proposal ----------------------- Also, I did consider an alternative API, where the Upload method is invoked on the Container object of target folder of the uploaded file. The return value of Upload would be a newly created d-Bus object representing the upload. The CancelTransfer method would belong to this new object and the progress of the transfer would be published in properties of the transfer object. The GetCurrentTransfers would remain on the com.intel.UPnP.MediaDevice interface but would return an array of object paths of the transfer objects rather than an array of transfer IDs. This would probably be a cleaner interface, and would do away with the TransferID variable. However, I decided not to do this as it would be more work for both the client and media-service-upnp. The clients would need to create and maintain a new d-Bus object and media-service-upnp would need to maintain a new virtual tree of d-bus transfer objects. Also, the lifecyle of the transferObjects would be tricky. Who should delete them? Should media-service-upnp create transfer objects on start up to reflect transfers on going on each DMS before media-service-upnp was started? My feeling is that the initial proposal is the simpler one, but again, I'd like to get your thoughts on this. Mark _______________________________________________ dLeyna mailing list dLeyna(a)lists.01.org https://lists.01.org/mailman/listinfo/dleyna

Hi Luc, Okay, I'll add the signals. If it's okay with everyone, I will do this in a separate pull request.

Hi Mark, A signal to notify the app if the upload has succeeded or failed would be nice, just to avoid polling. Otherwise, the app can of course call GetTransferStatus periodically, but then it would be more useful if GetTransferStatus also returned a percentage or a number of bytes transferred so that the app could show a progress bar. Luc On 06/19/2012 02:33 PM, Mark D Ryan wrote: > Hi All, > > I've been working on an API extension for media-service-upnp that will > allow clients to easily upload files to a DMS. I have a working > implementation on my fork but I thought it might be a good idea to > discuss the API changes here before sending my pull request. The plan > is as follows: > > Add four new methods to the com.intel.UPnP.MediaDevice interface. > > 1) Upload(s DisplayName, s FilePath, o ContainerPath) -> (i TransferID, > o ObjectPath) > > This command would initiate the upload of the local file specified by > FilePath to the Container specified by ContainerPath. The file will be > assigned the Friendly Name DisplayName. This method creates a new empty > object on the server and instructs the server to begin to upload the > local file from the client. The Upload method returns as soon as the > server has begun to upload the file and not when the server has finished > uploading the file. Upload returns two output parameters: a TransferID > that can be used to monitor the upload and to cancel it, and ObjectPath > which contains the path of the newly created object. > > An example of invoking this function with mediaconsole would be > > upnp = UPNP() > upnp.servers() > > MediaTomb /com/intel/MediaServiceUPnP/**server/0 > My Media /com/intel/MediaServiceUPnP/**server/1 > > device = Device("/com/intel/**MediaServiceUPnP/server/1") > device.upload("Test", "/home/user/Pictures/Cherry Tree.jpg", > "/com/intel/MediaServiceUPnP/**server/1/** > 376631393437303032643630666661**303632663161383831623237653835**3139") > > Transfer ID: 3 > Path: /com/intel/MediaServiceUPnP/**server/1/** > 653565366537366266383766393834**613563306364376137323662366334**6239 > > > 2) GetTransferStatus(i TransferID) -> (s TransferStatus, i > TransferLength, i TransferTotal) > > Retrieves information on the status of an upload operation. TransferID > is the ID returned by a call to Upload. The method returns a > TransferStatus which can be set to 1 of 4 values, "IN_PROGRESS", > "STOPPED", "ERROR", "COMPLETED", and two integers which indicate the > total length of the transfer and the amount of bytes transferred so far. > > GetTransferStatus will return valid results for up to 30 seconds after > the transfer has finished. > > 3) CancelTransfer(i TransferID) > > Cancels an ongoing transfer. > > 4) GetCurrentTransfers() -> (ai) > > Returns an array of transfer IDs of the transfers currently in progress. > > This is my proposal. I'm wondering whether to provide a notification to > indicate whether the transfer has completed or failed. Currently, I'm > not planning to do this but I'd like to hear your thoughts. My feeling > is that upload clients will need to call GetTransferStatus periodically > to determine how the transfer is progressing, and so will not need this > extra signal. > > On the other hand, if we want to implement an upload manager that > monitors all the uploads being made to the server, regardless of their > initiators, we would need some signals. > > > Alternative Proposal > ----------------------- > > Also, I did consider an alternative API, where the Upload method is > invoked on the Container object of target folder of the uploaded file. > The return value of Upload would be a newly created d-Bus object > representing the upload. The CancelTransfer method would belong to this > new object and the progress of the transfer would be published in > properties of the transfer object. The GetCurrentTransfers would remain > on the com.intel.UPnP.MediaDevice interface but would return an array of > object paths of the transfer objects rather than an array of transfer > IDs. > > This would probably be a cleaner interface, and would do away with the > TransferID variable. However, I decided not to do this as it would be > more work for both the client and media-service-upnp. The clients would > need to create and maintain a new d-Bus object and media-service-upnp > would need to maintain a new virtual tree of d-bus transfer objects. > Also, the lifecyle of the transferObjects would be tricky. Who should > delete them? Should media-service-upnp create transfer objects on start > up to reflect transfers on going on each DMS before media-service-upnp > was started? My feeling is that the initial proposal is the simpler > one, but again, I'd like to get your thoughts on this. > > Mark > > > ______________________________**_________________ > dLeyna mailing list > dLeyna(a)lists.01.org > https://lists.01.org/mailman/**listinfo/dleyna<https://lists.01.org/ma... > ______________________________**_________________ dLeyna mailing list dLeyna(a)lists.01.org https://lists.01.org/mailman/**listinfo/dleyna<https://lists.01.org/ma...

Hi Ludovic,**** ** ** Sure, I’ll change STOPPED to CANCELLED.**** ** ** How about,**** ** ** Upload**** GetUploadStatus**** GetUploadIDs**** CancelUpload**** ** ** That would be more in line with the other method names in which the verb comes first.**** ** ** Mark**** ** ** *From:* dleyna-bounces(a)lists.01.org [mailto:dleyna-bounces@lists.01.org] *On Behalf Of *Ferrandis, Ludovic *Sent:* Tuesday, June 19, 2012 3:16 PM *To:* Luc Yriarte *Cc:* dleyna(a)lists.01.org *Subject:* Re: [dLeyna] Upload API**** ** ** Hi Mark, STOPPED is confusing. It seems we could pause and resume the upload. Maybe CANCELED will be more appropriated. Like Luc, I think a signal is needed to avoid application to poll. About the API naming, maybe we could have the same "root" word for all APIs, Upload or Transfert but not both. I think Upload is a good one ->Upload() ->UploadGetStatus() ->UploadGetList() ->UploadCancel() Ludo **** On Tue, Jun 19, 2012 at 3:00 PM, Luc Yriarte <luc.yriarte(a)linux.intel.com&gt; wrote:**** Hi Mark, A signal to notify the app if the upload has succeeded or failed would be nice, just to avoid polling. Otherwise, the app can of course call GetTransferStatus periodically, but then it would be more useful if GetTransferStatus also returned a percentage or a number of bytes transferred so that the app could show a progress bar. Luc**** On 06/19/2012 02:33 PM, Mark D Ryan wrote:**** Hi All, I've been working on an API extension for media-service-upnp that will allow clients to easily upload files to a DMS. I have a working implementation on my fork but I thought it might be a good idea to discuss the API changes here before sending my pull request. The plan is as follows: Add four new methods to the com.intel.UPnP.MediaDevice interface. 1) Upload(s DisplayName, s FilePath, o ContainerPath) -> (i TransferID, o ObjectPath) This command would initiate the upload of the local file specified by FilePath to the Container specified by ContainerPath. The file will be assigned the Friendly Name DisplayName. This method creates a new empty object on the server and instructs the server to begin to upload the local file from the client. The Upload method returns as soon as the server has begun to upload the file and not when the server has finished uploading the file. Upload returns two output parameters: a TransferID that can be used to monitor the upload and to cancel it, and ObjectPath which contains the path of the newly created object. An example of invoking this function with mediaconsole would be upnp = UPNP() upnp.servers() MediaTomb /com/intel/MediaServiceUPnP/server/0 My Media /com/intel/MediaServiceUPnP/server/1 device = Device("/com/intel/MediaServiceUPnP/server/1") device.upload("Test", "/home/user/Pictures/Cherry Tree.jpg", "/com/intel/MediaServiceUPnP/server/1/376631393437303032643630666661303632663161383831623237653835 3139") Transfer ID: 3 Path: /com/intel/MediaServiceUPnP/server/1/6535653665373662663837663938346135633063643761373236623663346239 2) GetTransferStatus(i TransferID) -> (s TransferStatus, i TransferLength, i TransferTotal) Retrieves information on the status of an upload operation. TransferID is the ID returned by a call to Upload. The method returns a TransferStatus which can be set to 1 of 4 values, "IN_PROGRESS", "STOPPED", "ERROR", "COMPLETED", and two integers which indicate the total length of the transfer and the amount of bytes transferred so far. GetTransferStatus will return valid results for up to 30 seconds after the transfer has finished. 3) CancelTransfer(i TransferID) Cancels an ongoing transfer. 4) GetCurrentTransfers() -> (ai) Returns an array of transfer IDs of the transfers currently in progress. This is my proposal. I'm wondering whether to provide a notification to indicate whether the transfer has completed or failed. Currently, I'm not planning to do this but I'd like to hear your thoughts. My feeling is that upload clients will need to call GetTransferStatus periodically to determine how the transfer is progressing, and so will not need this extra signal. On the other hand, if we want to implement an upload manager that monitors all the uploads being made to the server, regardless of their initiators, we would need some signals. Alternative Proposal ----------------------- Also, I did consider an alternative API, where the Upload method is invoked on the Container object of target folder of the uploaded file. The return value of Upload would be a newly created d-Bus object representing the upload. The CancelTransfer method would belong to this new object and the progress of the transfer would be published in properties of the transfer object. The GetCurrentTransfers would remain on the com.intel.UPnP.MediaDevice interface but would return an array of object paths of the transfer objects rather than an array of transfer IDs. This would probably be a cleaner interface, and would do away with the TransferID variable. However, I decided not to do this as it would be more work for both the client and media-service-upnp. The clients would need to create and maintain a new d-Bus object and media-service-upnp would need to maintain a new virtual tree of d-bus transfer objects. Also, the lifecyle of the transferObjects would be tricky. Who should delete them? Should media-service-upnp create transfer objects on start up to reflect transfers on going on each DMS before media-service-upnp was started? My feeling is that the initial proposal is the simpler one, but again, I'd like to get your thoughts on this. Mark _______________________________________________ dLeyna mailing list dLeyna(a)lists.01.org https://lists.01.org/mailman/listinfo/dleyna**** _______________________________________________ dLeyna mailing list dLeyna(a)lists.01.org https://lists.01.org/mailman/listinfo/dleyna**** -- **** Ludovic Ferrandis**** Open Source Technology Center**** --------------------------------------------------------------------- Intel Corporation SAS (French simplified joint stock company) Registered headquarters: "Les Montalets"- 2, rue de Paris, 92196 Meudon Cedex, France Registration Number: 302 456 199 R.C.S. NANTERRE Capital: 4,572,000 Euros**** ** ** --------------------------------------------------------------------- Intel Corporation SAS (French simplified joint stock company) Registered headquarters: "Les Montalets"- 2, rue de Paris, 92196 Meudon Cedex, France Registration Number: 302 456 199 R.C.S. NANTERRE Capital: 4,572,000 Euros This e-mail and any attachments may contain confidential material for the sole use of the intended recipient(s). Any review or distribution by others is strictly prohibited. If you are not the intended recipient, please contact the sender and delete all copies.

> Alternative Proposal > ----------------------- > > Also, I did consider an alternative API, where the Upload method is > invoked on the Container object of target folder of the uploaded file. > The return value of Upload would be a newly created d-Bus object > representing the upload. The CancelTransfer method would belong to this > new object and the progress of the transfer would be published in > properties of the transfer object. The GetCurrentTransfers would remain > on the com.intel.UPnP.MediaDevice interface but would return an array of > object paths of the transfer objects rather than an array of transfer > IDs. How would you handle DLNA.ORG_AnyContainer with that?

_______________________________________________ dLeyna mailing list dLeyna(a)lists.01.org https://lists.01.org/mailman/listinfo/dleyna

On Di, 2012-06-19 at 16:27 +0200, Mark D Ryan wrote: > > > > How would you handle DLNA.ORG_AnyContainer with that? > > > > Good point. I hadn't thought about this. > > I guess with the first proposal we could either define a separate > Method, UploadToAnyContainer or define a d-Bus path to represent the > AnyContainer that could be passed to Upload. The d-Bus path would not > point to any existing object. > > In the alternative proposal I guess we would need to actually maintain > one d-Bus object per server to represent the AnyContainer. This would > complicate matters further. > > My preference would be to stick with the original proposal but to add a > separate method, UploadToAnyContainer. Any objections? Sounds less complicated. What's your strategy for a DMS that doesn't support it? Throw an error or simulate upload-any by looking for suitable folders on the server?